blib/lib/Web/Simple.pm

filter: Statementstmt 100% 38 / 38 Branchbran 50.0% 1 / 2 Conditioncond 66.6% 2 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 100% 9 / 9 Podpod n/a totaltotal 92.5% 50 / 54 CC 3 SCAR 4.4
CC
3
Cov
95%
import
3.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.5
« blib/lib/Web/Dispatch/Node.pm ↑ Summary blib/lib/Web/Dispatch/Wrapper.pm »
1 package Web::Simple;
2  
3 15 ▶use strictures 1;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 15 ▶use warnings::illegalproto ();
Subroutine BEGIN: called CC=1 SCAR=0.0
5 15 ▶use Moo ();
Subroutine BEGIN: called CC=1 SCAR=0.0
6 15 ▶use Web::Dispatch::Wrapper ();
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 15 our $VERSION = '0.037';
9  
10 15 ▶sub import {
Subroutine import: called CC=3 SCAR=11.0
11 15 my ($class, $app_package) = @_;
12 15 ▶ $app_package ||= caller;
Condition66%2/3
$app_package ||= caller
l!l&&r!l&&!r
780
MC/DC0%0/2
$app_package ||= caller
$app_package caller
Truth table66%2/3
A ||= B
A= $app_packageB= caller
ABresult
1X1
011
000
13 15 $class->_export_into($app_package);
14 15 ▶ eval "package $app_package; use Web::Dispatch::Wrapper; use Moo; 1"
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
Branch: 1 branch
BranchTrueFalseTotal
eval "package $app_package; use Web::Dispatch::Wrapper; use Moo; 1" or die "Failed to setup app package: $@" 15 0 15
15 or die "Failed to setup app package: $@";
16 15 strictures->import;
17 15 warnings::illegalproto->unimport;
18 }
19  
20 15 ▶sub _export_into {
Subroutine _export_into: called CC=1 SCAR=0.0
21 15 my ($class, $app_package) = @_;
22 {
23 15 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
24 15 *{"${app_package}::PSGI_ENV"} = sub () { -1 };
25 15 require Web::Simple::Application;
26 15 unshift(@{"${app_package}::ISA"}, 'Web::Simple::Application');
27 }
28 15 (my $name = $app_package) =~ s/::/\//g;
29 15 $INC{"${name}.pm"} = 'Set by "use Web::Simple;" invocation';
30 }
31  
32 15 1;
33  
34 =head1 NAME
35  
36 Web::Simple - A quick and easy way to build simple web applications
37  
38  
39 =head1 SYNOPSIS
40  
41 #!/usr/bin/env perl
42  
43 package HelloWorld;
44 use Web::Simple;
45  
46 sub dispatch_request {
47 GET => sub {
48 [ 200, [ 'Content-type', 'text/plain' ], [ 'Hello world!' ] ]
49 },
50 '' => sub {
51 [ 405, [ 'Content-type', 'text/plain' ], [ 'Method not allowed' ] ]
52 }
53 }
54  
55 HelloWorld->run_if_script;
56  
57 If you save this file into your cgi-bin as C<hello-world.cgi> and then visit:
58  
59 http://my.server.name/cgi-bin/hello-world.cgi/
60  
61 you'll get the "Hello world!" string output to your browser. At the same time
62 this file will also act as a class module, so you can save it as HelloWorld.pm
63 and use it as-is in test scripts or other deployment mechanisms.
64  
65 Note that you should retain the ->run_if_script even if your app is a
66 module, since this additionally makes it valid as a .psgi file, which can
67 be extremely useful during development.
68  
69 For more complex examples and non-CGI deployment, see
70 L<Web::Simple::Deployment>. To get help with L<Web::Simple>, please connect to
71 the irc.perl.org IRC network and join #web-simple.
72  
73 =head1 DESCRIPTION
74  
75 The philosophy of L<Web::Simple> is to keep to an absolute bare minimum for
76 everything. It is not designed to be used for large scale applications;
77 the L<Catalyst> web framework already works very nicely for that and is
78 a far more mature, well supported piece of software.
79  
80 However, if you have an application that only does a couple of things, and
81 want to not have to think about complexities of deployment, then L<Web::Simple>
82 might be just the thing for you.
83  
84 The only public interface the L<Web::Simple> module itself provides is an
85 C<import> based one:
86  
87 use Web::Simple 'NameOfApplication';
88  
89 This sets up your package (in this case "NameOfApplication" is your package)
90 so that it inherits from L<Web::Simple::Application> and imports L<strictures>,
91 as well as installs a C<PSGI_ENV> constant for convenience, as well as some
92 other subroutines.
93  
94 Importing L<strictures> will automatically make your code use the C<strict> and
95 C<warnings> pragma, so you can skip the usual:
96  
97 use strict;
98 use warnings FATAL => 'all';
99  
100 provided you 'use Web::Simple' at the top of the file. Note that we turn
101 on *fatal* warnings so if you have any warnings at any point from the file
102 that you did 'use Web::Simple' in, then your application will die. This is,
103 so far, considered a feature.
104  
105 When we inherit from L<Web::Simple::Application> we also use L<Moo>, which is
106 the the equivalent of:
107  
108 {
109 package NameOfApplication;
110 use Moo;
111 extends 'Web::Simple::Application';
112 }
113  
114 So you can use L<Moo> features in your application, such as creating attributes
115 using the C<has> subroutine, etc. Please see the documentation for L<Moo> for
116 more information.
117  
118 It also exports the following subroutines for use in dispatchers:
119  
120 response_filter { ... };
121  
122 redispatch_to '/somewhere';
123  
124 Finally, import sets
125  
126 $INC{"NameOfApplication.pm"} = 'Set by "use Web::Simple;" invocation';
127  
128 so that perl will not attempt to load the application again even if
129  
130 require NameOfApplication;
131  
132 is encountered in other code.
133  
134 One important thing to remember when using
135  
136 NameOfApplication->run_if_script;
137  
138 At the end of your app is that this call will create an instance of your app
139 for you automatically, regardless of context. An easier way to think of this
140 would be if the method were more verbosely named
141  
142 NameOfApplication->run_request_if_script_else_turn_coderef_for_psgi;
143  
144 =head1 DISPATCH STRATEGY
145  
146 L<Web::Simple> despite being straightforward to use, has a powerful system
147 for matching all sorts of incoming URLs to one or more subroutines. These
148 subroutines can be simple actions to take for a given URL, or something
149 more complicated, including entire L<Plack> applications, L<Plack::Middleware>
150 and nested subdispatchers.
151  
152 =head2 Examples
153  
154 sub dispatch_request {
155 (
156 # matches: GET /user/1.htm?show_details=1
157 # GET /user/1.htm
158 'GET + /user/* + ?show_details~ + .htm|.html|.xhtml' => sub {
159 my ($self, $user_id, $show_details) = @_;
160 ...
161 },
162 # matches: POST /user?username=frew
163 # POST /user?username=mst&first_name=matt&last_name=trout
164 'POST + /user + ?username=&*' => sub {
165 my ($self, $username, $misc_params) = @_;
166 ...
167 },
168 # matches: DELETE /user/1/friend/2
169 'DELETE + /user/*/friend/*' => sub {
170 my ($self, $user_id, $friend_id) = @_;
171 ...
172 },
173 # matches: PUT /user/1?first_name=Matt&last_name=Trout
174 'PUT + /user/* + ?first_name~&last_name~' => sub {
175 my ($self, $user_id, $first_name, $last_name) = @_;
176 ...
177 },
178 '/user/*/...' => sub {
179 my $user_id = $_[1];
180 (
181 # matches: PUT /user/1/role/1
182 'PUT + /role/*' => sub {
183 my $role_id = $_[1];
184 ...
185 },
186 # matches: DELETE /user/1/role/1
187 'DELETE + /role/*' => sub {
188 my $role_id = $_[1];
189 ...
190 },
191 );
192 },
193 );
194 }
195  
196 =head2 The dispatch cycle
197  
198 At the beginning of a request, your app's dispatch_request method is called
199 with the PSGI $env as an argument. You can handle the request entirely in
200 here and return a PSGI response arrayref if you want:
201  
202 sub dispatch_request {
203 my ($self, $env) = @_;
204 [ 404, [ 'Content-type' => 'text/plain' ], [ 'Amnesia == fail' ] ]
205 }
206  
207 However, generally, instead of that, you return a set of route/target
208 pairs:
209  
210 sub dispatch_request {
211 my $self = shift;
212 (
213 '/' => sub { redispatch_to '/index.html' },
214 '/user/*' => sub { $self->show_user($_[1]) },
215 'POST + %*' => 'handle_post',
216 ...
217 );
218 }
219  
220 Well, a sub is a valid PSGI response too (for ultimate streaming and async
221 cleverness). If you want to return a PSGI sub you have to wrap it into an
222 array ref.
223  
224 sub dispatch_request {
225 [ sub {
226 my $respond = shift;
227 # This is pure PSGI here, so read perldoc PSGI
228 } ]
229 }
230  
231 If you return a string followed by a subroutine or method name, the string is
232 treated as a match specification - and if the test is passed, the subroutine
233 is called as a method and passed any matched arguments (see below for more details).
234  
235 You can also return a plain subroutine which will be called with just C<$env>
236 - remember that in this case if you need C<$self> you B<must> close over it.
237  
238 If you return a normal object, L<Web::Simple> will simply return it upwards on
239 the assumption that a response_filter (or some arbitrary L<Plack::Middleware>)
240 somewhere will convert it to something useful. This allows:
241  
242 sub dispatch_request {
243 my $self = shift;
244 (
245 '.html' => sub { response_filter { $self->render_zoom($_[0]) } },
246 '/user/*' => sub { $self->users->get($_[1]) },
247 );
248 }
249  
250 An alternative to using string + suborutine to declare a route is to use
251 the sub prototype -
252  
253 sub dispatch_request {
254 my $self = shift;
255 (
256 sub (.html) { response_filter { $self->render_zoom($_[0]) } },
257 sub (/user/) { $self->users->get($_[1]) },
258 $self->can('handle_post'), # if declared as 'sub handle_post (...) {'
259 )
260 }
261  
262 This can be useful sugar, especially if you want to keep method-based
263 dispatchers' route specifications on the methods.
264  
265 to render a user object to HTML, if there is an incoming URL such as:
266  
267 http://myweb.org/user/111.html
268  
269 This works because as we descend down the dispachers, we first match
270 C<sub (.html)>, which adds a C<response_filter> (basically a specialized routine
271 that follows the L<Plack::Middleware> specification), and then later we also
272 match C<sub (/user/*)> which gets a user and returns that as the response.
273 This user object 'bubbles up' through all the wrapping middleware until it hits
274 the C<response_filter> we defined, after which the return is converted to a
275 true html response.
276  
277 However, two types of objects are treated specially - a C<Plack::Component> object
278 will have its C<to_app> method called and be used as a dispatcher:
279  
280 sub dispatch_request {
281 my $self = shift;
282 (
283 '/static/...' => sub { Plack::App::File->new(...) },
284 ...
285 );
286 }
287  
288 A L<Plack::Middleware> object will be used as a filter for the rest of the
289 dispatch being returned into:
290  
291 ## responds to /admin/track_usage AND /admin/delete_accounts
292  
293 sub dispatch_request {
294 my $self = shift;
295 (
296 '/admin/**' => sub {
297 Plack::Middleware::Session->new(%opts);
298 },
299 '/admin/track_usage' => sub {
300 ## something that needs a session
301 },
302 '/admin/delete_accounts' => sub {
303 ## something else that needs a session
304 },
305 );
306 }
307  
308 Note that this is for the dispatch being B<returned> to, so if you want to
309 provide it inline you need to do:
310  
311 ## ALSO responds to /admin/track_usage AND /admin/delete_accounts
312  
313 sub dispatch_request {
314 my $self = shift;
315 (
316 '/admin/...' => sub {
317 (
318 sub {
319 Plack::Middleware::Session->new(%opts);
320 },
321 '/track_usage' => sub {
322 ## something that needs a session
323 },
324 '/delete_accounts' => sub {
325 ## something else that needs a session
326 },
327 );
328 }
329 );
330 }
331  
332 And that's it - but remember that all this happens recursively - it's
333 dispatchers all the way down. A URL incoming pattern will run all matching
334 dispatchers and then hit all added filters or L<Plack::Middleware>.
335  
336 =head2 Web::Simple match specifications
337  
338 =head3 Method matches
339  
340 'GET' => sub {
341  
342 A match specification beginning with a capital letter matches HTTP requests
343 with that request method.
344  
345 =head3 Path matches
346  
347 '/login' => sub {
348  
349 A match specification beginning with a / is a path match. In the simplest
350 case it matches a specific path. To match a path with a wildcard part, you
351 can do:
352  
353 '/user/*' => sub {
354 $self->handle_user($_[1])
355  
356 This will match /user/<anything> where <anything> does not include a literal
357 / character. The matched part becomes part of the match arguments. You can
358 also match more than one part:
359  
360 '/user/*/*' => sub {
361 my ($self, $user_1, $user_2) = @_;
362  
363 '/domain/*/user/*' => sub {
364 my ($self, $domain, $user) = @_;
365  
366 and so on. To match an arbitrary number of parts, use C<**>:
367  
368 '/page/**' => sub {
369 my ($self, $match) = @_;
370  
371 This will result in a single element for the entire match. Note that you can do
372  
373 '/page/**/edit' => sub {
374  
375 to match an arbitrary number of parts up to but not including some final
376 part.
377  
378 Note: Since Web::Simple handles a concept of file extensions, C<*> and C<**>
379 matchers will not by default match things after a final dot, and this
380 can be modified by using C<*.*> and C<**.*> in the final position, e.g.:
381  
382 /one/* matches /one/two.three and captures "two"
383 /one/*.* matches /one/two.three and captures "two.three"
384 /** matches /one/two.three and captures "one/two"
385 /**.* matches /one/two.three and captures "one/two.three"
386  
387 Finally,
388  
389 '/foo/...' => sub {
390  
391 Will match C</foo/> on the beginning of the path B<and> strip it. This is
392 designed to be used to construct nested dispatch structures, but can also prove
393 useful for having e.g. an optional language specification at the start of a
394 path.
395  
396 Note that the '...' is a "maybe something here, maybe not" so the above
397 specification will match like this:
398  
399 /foo # no match
400 /foo/ # match and strip path to '/'
401 /foo/bar/baz # match and strip path to '/bar/baz'
402  
403 Almost the same,
404  
405 '/foo...' => sub {
406  
407 Will match on C</foo/bar/baz>, but also include C</foo>. Otherwise it
408 operates the same way as C</foo/...>.
409  
410 /foo # match and strip path to ''
411 /foo/ # match and strip path to '/'
412 /foo/bar/baz # match and strip path to '/bar/baz'
413  
414 Please note the difference between C<sub(/foo/...)> and C<sub(/foo...)>. In
415 the first case, this is expecting to find something after C</foo> (and fails to
416 match if nothing is found), while in the second case we can match both C</foo>
417 and C</foo/more/to/come>. The following are roughly the same:
418  
419 '/foo' => sub { 'I match /foo' },
420 '/foo/...' => sub {
421 (
422 '/bar' => sub { 'I match /foo/bar' },
423 '/*' => sub { 'I match /foo/{id}' },
424 );
425 }
426  
427 Versus
428  
429 '/foo...' => sub {
430 (
431 '~' => sub { 'I match /foo' },
432 '/bar' => sub { 'I match /foo/bar' },
433 '/*' => sub { 'I match /foo/{id}' },
434 );
435 }
436  
437 You may prefer the latter example should you wish to take advantage of
438 subdispatchers to scope common activities. For example:
439  
440 '/user...' => sub {
441 my $user_rs = $schema->resultset('User');
442 (
443 '~' => sub { $user_rs },
444 '/*' => sub { $user_rs->find($_[1]) },
445 );
446 }
447  
448 You should note the special case path match C<sub (~)> which is only meaningful
449 when it is contained in this type of path match. It matches to an empty path.
450  
451 =head4 Naming your patch matches
452  
453 Any C<*>, C<**>, C<*.*>, or C<**.*> match can be followed with C<:name> to make it into a named
454 match, so:
455  
456 '/*:one/*:two/*:three/*:four' => sub {
457 "I match /1/2/3/4 capturing { one => 1, two => 2, three => 3, four => 4 }"
458 }
459
460 '/**.*:allofit' => sub {
461 "I match anything capturing { allofit => \$whole_path }"
462 }
463  
464 In the specific case of a simple single-* match, the * may be omitted, to
465 allow you to write:
466  
467 '/:one/:two/:three/:four' => sub {
468 "I match /1/2/3/4 capturing { one => 1, two => 2, three => 3, four => 4 }"
469 }
470  
471 =head4 C</foo> and C</foo/> are different specs
472  
473 As you may have noticed with the difference between C<'/foo/...'> and
474 C<'/foo...'>, trailing slashes in path specs are significant. This is
475 intentional and necessary to retain the ability to use relative links on
476 websites. Let's demonstrate on this link:
477  
478 <a href="bar">bar</a>
479  
480 If the user loads the url C</foo/> and clicks on this link, they will be
481 sent to C</foo/bar>. However when they are on the url C</foo> and click this
482 link, then they will be sent to C</bar>.
483  
484 This makes it necessary to be explicit about the trailing slash.
485  
486 =head3 Extension matches
487  
488 '.html' => sub {
489  
490 will match .html from the path (assuming the subroutine itself returns
491 something, of course). This is normally used for rendering - e.g.:
492  
493 '.html' => sub {
494 response_filter { $self->render_html($_[1]) }
495 }
496  
497 Additionally,
498  
499 '.*' => sub {
500  
501 will match any extension and supplies the extension as a match argument.
502  
503 =head3 Query and body parameter matches
504  
505 Query and body parameters can be match via
506  
507 '?<param spec>' => sub { # match URI query
508 '%<param spec>' => sub { # match body params
509  
510 The body spec will match if the request content is either
511 application/x-www-form-urlencoded or multipart/form-data - the latter
512 of which is required for uploads - see below.
513  
514 The param spec is elements of one of the following forms:
515  
516 param~ # optional parameter
517 param= # required parameter
518 @param~ # optional multiple parameter
519 @param= # required multiple parameter
520 :param~ # optional parameter in hashref
521 :param= # required parameter in hashref
522 :@param~ # optional multiple in hashref
523 :@param= # required multiple in hashref
524 * # include all other parameters in hashref
525 @* # include all other parameters as multiple in hashref
526  
527 separated by the C<&> character. The arguments added to the request are
528 one per non-C<:>/C<*> parameter (scalar for normal, arrayref for multiple),
529 plus if any C<:>/C<*> specs exist a hashref containing those values. If a
530 parameter has no value, i.e. appears as '?foo&', a value of 1 will be
531 captured.
532  
533 Please note that if you specify a multiple type parameter match, you are
534 ensured of getting an arrayref for the value, EVEN if the current incoming
535 request has only one value. However if a parameter is specified as single
536 and multiple values are found, the last one will be used.
537  
538 For example to match a C<page> parameter with an optional C<order_by> parameter one
539 would write:
540  
541 '?page=&order_by~' => sub {
542 my ($self, $page, $order_by) = @_;
543 return unless $page =~ /^\d+$/;
544 $order_by ||= 'id';
545 response_filter {
546 $_[1]->search_rs({}, { page => $page, order_by => $order_by });
547 }
548 }
549  
550 to implement paging and ordering against a L<DBIx::Class::ResultSet> object.
551  
552 Another Example: To get all parameters as a hashref of arrayrefs, write:
553  
554 '?@*' => sub {
555 my ($self, $params) = @_;
556 ...
557  
558 To get two parameters as a hashref, write:
559  
560 '?:user~&:domain~' => sub {
561 my ($self, $params) = @_; # params contains only 'user' and 'domain' keys
562  
563 You can also mix these, so:
564  
565 '?foo=&@bar~&:coffee=&@*' => sub {
566 my ($self, $foo, $bar, $params) = @_;
567  
568 where $bar is an arrayref (possibly an empty one), and $params contains
569 arrayref values for all parameters B<not> mentioned and a scalar value for
570 the 'coffee' parameter.
571  
572 Note, in the case where you combine arrayref, single parameter and named
573 hashref style, the arrayref and single parameters will appear in C<@_> in the
574 order you defined them in the prototype, but all hashrefs will merge into a
575 single C<$params>, as in the example above.
576  
577 =head3 Upload matches
578  
579 '*foo=' => sub { # param specifier can be anything valid for query or body
580  
581 The upload match system functions exactly like a query/body match, except
582 that the values returned (if any) are C<Web::Dispatch::Upload> objects.
583  
584 Note that this match type will succeed in two circumstances where you might
585 not expect it to - first, when the field exists but is not an upload field
586 and second, when the field exists but the form is not an upload form (i.e.
587 content type "application/x-www-form-urlencoded" rather than
588 "multipart/form-data"). In either of these cases, what you'll get back is
589 a C<Web::Dispatch::NotAnUpload> object, which will C<die> with an error
590 pointing out the problem if you try and use it. To be sure you have a real
591 upload object, call
592  
593 $upload->is_upload # returns 1 on a valid upload, 0 on a non-upload field
594  
595 and to get the reason why such an object is not an upload, call
596  
597 $upload->reason # returns a reason or '' on a valid upload.
598  
599 Other than these two methods, the upload object provides the same interface
600 as L<Plack::Request::Upload> with the addition of a stringify to the temporary
601 filename to make copying it somewhere else easier to handle.
602  
603 =head3 Combining matches
604  
605 Matches may be combined with the + character - e.g.
606  
607 'GET + /user/*' => sub {
608  
609 to create an AND match. They may also be combined with the | character - e.g.
610  
611 'GET|POST' => sub {
612  
613 to create an OR match. Matches can be nested with () - e.g.
614  
615 '(GET|POST + /user/*)' => sub {
616  
617 and negated with ! - e.g.
618  
619 '!/user/foo + /user/*' => sub {
620  
621 ! binds to the immediate rightmost match specification, so if you want
622 to negate a combination you will need to use
623  
624 '!(POST|PUT|DELETE)' => sub {
625  
626 and | binds tighter than +, so
627  
628 '(GET|POST) + /user/*' => sub {
629  
630 and
631  
632 'GET|POST + /user/*' => sub {
633  
634 are equivalent, but
635  
636 '(GET + /admin/...) | (POST + /admin/...)' => sub {
637  
638 and
639  
640 'GET + /admin/... | POST + /admin/...' => sub {
641  
642 are not - the latter is equivalent to
643  
644 'GET + (/admin/...|POST) + /admin/...' => sub {
645  
646 which will never match!
647  
648 =head3 Whitespace
649  
650 Note that for legibility you are permitted to use whitespace:
651  
652 'GET + /user/*' => sub {
653  
654 but it will be ignored. This is because the perl parser strips whitespace
655 from subroutine prototypes, so this is equivalent to
656  
657 'GET+/user/*' => sub {
658  
659 =head3 Accessing parameters via C<%_>
660  
661 If your dispatch specification causes your dispatch subroutine to receive
662 a hash reference as its first argument, the contained named parameters
663 will be accessible via C<%_>.
664  
665 This can be used to access your path matches, if they are named:
666  
667 'GET + /foo/:path_part' => sub {
668 [ 200,
669 ['Content-type' => 'text/plain'],
670 ["We are in $_{path_part}"],
671 ];
672 }
673  
674 Or, if your first argument would be a hash reference containing named
675 query parameters:
676  
677 'GET + /foo + ?:some_param=' => sub {
678 [ 200,
679 ['Content-type' => 'text/plain'],
680 ["We received $_{some_param} as parameter"],
681 ];
682 }
683  
684 Of course this also works when all you are doing is slurping the whole set
685 of parameters by their name:
686  
687 'GET + /foo + ?*' => sub {
688 [ 200,
689 ['Content-type' => 'text/plain'],
690 [exists($_{foo}) ? "Received a foo: $_{foo}" : "No foo!"],
691 ],
692 }
693  
694 Note that only the first hash reference will be available via C<%_>. If
695 you receive additional hash references, you will need to access them as
696 usual.
697  
698 =head3 Accessing the PSGI env hash
699  
700 In some cases you may wish to get the raw PSGI env hash - to do this,
701 you can either use a plain sub:
702  
703 sub {
704 my ($env) = @_;
705 ...
706 }
707  
708 or use the C<PSGI_ENV> constant exported to retrieve it from C<@_>:
709  
710 'GET + /foo + ?some_param=' => sub {
711 my $param = $_[1];
712 my $env = $_[PSGI_ENV];
713 }
714  
715 but note that if you're trying to add a middleware, you should simply use
716 Web::Simple's direct support for doing so.
717  
718 =head1 EXPORTED SUBROUTINES
719  
720 =head2 response_filter
721  
722 response_filter {
723 # Hide errors from the user because we hates them, preciousss
724 if (ref($_[0]) eq 'ARRAY' && $_[0]->[0] == 500) {
725 $_[0] = [ 200, @{$_[0]}[1..$#{$_[0]}] ];
726 }
727 return $_[0];
728 };
729  
730 The response_filter subroutine is designed for use inside dispatch subroutines.
731  
732 It creates and returns a special dispatcher that always matches, and calls
733 the block passed to it as a filter on the result of running the rest of the
734 current dispatch chain.
735  
736 Thus the filter above runs further dispatch as normal, but if the result of
737 dispatch is a 500 (Internal Server Error) response, changes this to a 200 (OK)
738 response without altering the headers or body.
739  
740 =head2 redispatch_to
741  
742 redispatch_to '/other/url';
743  
744 The redispatch_to subroutine is designed for use inside dispatch subroutines.
745  
746 It creates and returns a special dispatcher that always matches, and instead
747 of continuing dispatch re-delegates it to the start of the dispatch process,
748 but with the path of the request altered to the supplied URL.
749  
750 Thus if you receive a POST to C</some/url> and return a redispatch to
751 C</other/url>, the dispatch behaviour will be exactly as if the same POST
752 request had been made to C</other/url> instead.
753  
754 Note, this is not the same as returning an HTTP 3xx redirect as a response;
755 rather it is a much more efficient internal process.
756  
757 =head1 SECURITY CONSIDERATIONS
758  
759 Request bodies now have a maximum size, which defaults to 8 MiB.
760  
761 If you want to adjust the size, you need to change
762 C<$Web::Dispatch::ParamParser::MAX_BODY_SIZE>, for example,
763  
764 $Web::Dispatch::ParamParser::MAX_BODY_SIZE = 33554432; # 32MiB
765  
766 Requests with larger bodies will croak.
767  
768 You will need to validate the Content-Length header before dispatching it,
769 if you want a user-friendly response.
770  
771 =head1 CHANGES BETWEEN RELEASES
772  
773 =head2 Changes between 0.004 and 0.005
774  
775 =over 4
776  
777 =item * dispatch {} replaced by declaring a dispatch_request method
778  
779 dispatch {} has gone away - instead, you write:
780  
781 sub dispatch_request {
782 my $self = shift;
783 (
784 'GET /foo/' => sub { ... },
785 ...
786 );
787 }
788  
789 Note that this method is still B<returning> the dispatch code - just like
790 C<dispatch> did.
791  
792 Also note that you need the C<< my $self = shift >> since the magic $self
793 variable went away.
794  
795 =item * the magic $self variable went away.
796  
797 Just add C<< my $self = shift; >> while writing your C<< sub dispatch_request { >>
798 like a normal perl method.
799  
800 =item * subdispatch deleted - all dispatchers can now subdispatch
801  
802 In earlier releases you needed to write:
803  
804 subdispatch sub (/foo/...) {
805 ...
806 [
807 sub (GET /bar/) { ... },
808 ...
809 ]
810 }
811  
812 As of 0.005, you can instead write simply:
813  
814 sub (/foo/...) {
815 ...
816 (
817 sub (GET /bar/) { ... },
818 ...
819 )
820 }
821  
822 =back
823  
824 =head2 Changes since Antiquated Perl
825  
826 =over 4
827  
828 =item * filter_response renamed to response_filter
829  
830 This is a pure rename; a global search and replace should fix it.
831  
832 =item * dispatch [] changed to dispatch {}
833  
834 Simply changing
835  
836 dispatch [ sub(...) { ... }, ... ];
837  
838 to
839  
840 dispatch { sub(...) { ... }, ... };
841  
842 should work fine.
843  
844 =back
845  
846 =head1 DEVELOPMENT HISTORY
847  
848 Web::Simple was originally written to form part of my Antiquated Perl talk for
849 Italian Perl Workshop 2009, but in writing the bloggery example I realised
850 that having a bare minimum system for writing web applications that doesn't
851 drive me insane was rather nice and decided to spend my attempt at nanowrimo
852 for 2009 improving and documenting it to the point where others could use it.
853  
854 The Antiquated Perl talk can be found at L<http://www.shadowcat.co.uk/archive/conference-video/> and the slides are reproduced in this distribution under
855 L<Web::Simple::AntiquatedPerl>.
856  
857 =head1 COMMUNITY AND SUPPORT
858  
859 =head2 IRC channel
860  
861 irc.perl.org #web-simple
862  
863 =head2 No mailing list yet
864  
865 Because mst's non-work email is a bombsite so he'd never read it anyway.
866  
867 =head2 Git repository
868  
869 Gitweb is on http://git.shadowcat.co.uk/ and the clone URL is:
870  
871 git clone git://git.shadowcat.co.uk/catagits/Web-Simple.git
872  
873 =head1 AUTHOR
874  
875 Matt S. Trout (mst) <mst@shadowcat.co.uk>
876  
877 =head1 CONTRIBUTORS
878  
879 Devin Austin (dhoss) <dhoss@cpan.org>
880  
881 Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
882  
883 gregor herrmann (gregoa) <gregoa@debian.org>
884  
885 John Napiorkowski (jnap) <jjn1056@yahoo.com>
886  
887 Josh McMichael <jmcmicha@linus222.gsc.wustl.edu>
888  
889 Justin Hunter (arcanez) <justin.d.hunter@gmail.com>
890  
891 Kjetil Kjernsmo <kjetil@kjernsmo.net>
892  
893 markie <markie@nulletch64.dreamhost.com>
894  
895 Christian Walde (Mithaldu) <walde.christian@googlemail.com>
896  
897 nperez <nperez@cpan.org>
898  
899 Robin Edwards <robin.ge@gmail.com>
900  
901 Andrew Rodland (hobbs) <andrew@cleverdomain.org>
902  
903 Robert Sedlacek (phaylon) <r.sedlacek@shadowcat.co.uk>
904  
905 Hakim Cassimally (osfameron) <osfameron@cpan.org>
906  
907 Karen Etheridge (ether) <ether@cpan.org>
908  
909 Robert Rothenberg <perl@rhizomnic.com>
910  
911 =head1 COPYRIGHT
912  
913 Copyright (c) 2011 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
914 as listed above.
915  
916 =head1 LICENSE
917  
918 This library is free software and may be distributed under the same terms
919 as perl itself.
920  
921 =cut
« blib/lib/Web/Dispatch/Node.pm ↑ Summary blib/lib/Web/Dispatch/Wrapper.pm »