4 use warnings::illegalproto ();
6 use Web::Dispatch::Wrapper ();
8 our $VERSION = '0.030';
11 my ($class, $app_package) = @_;
12 $app_package ||= caller;
13 $class->_export_into($app_package);
14 eval "package $app_package; use Web::Dispatch::Wrapper; use Moo; 1"
15 or die "Failed to setup app package: $@";
17 warnings::illegalproto->unimport;
21 my ($class, $app_package) = @_;
24 *{"${app_package}::PSGI_ENV"} = sub () { -1 };
25 require Web::Simple::Application;
26 unshift(@{"${app_package}::ISA"}, 'Web::Simple::Application');
28 (my $name = $app_package) =~ s/::/\//g;
29 $INC{"${name}.pm"} = 'Set by "use Web::Simple;" invocation';
36 Web::Simple - A quick and easy way to build simple web applications
46 sub dispatch_request {
48 [ 200, [ 'Content-type', 'text/plain' ], [ 'Hello world!' ] ]
51 [ 405, [ 'Content-type', 'text/plain' ], [ 'Method not allowed' ] ]
55 HelloWorld->run_if_script;
57 If you save this file into your cgi-bin as C<hello-world.cgi> and then visit:
59 http://my.server.name/cgi-bin/hello-world.cgi/
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.
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.
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.
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.
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.
84 The only public interface the L<Web::Simple> module itself provides is an
87 use Web::Simple 'NameOfApplication';
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
94 Importing L<strictures> will automatically make your code use the C<strict> and
95 C<warnings> pragma, so you can skip the usual:
98 use warnings FATAL => 'all';
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.
105 When we inherit from L<Web::Simple::Application> we also use L<Moo>, which is
106 the the equivalent of:
109 package NameOfApplication;
111 extends 'Web::Simple::Application';
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
118 It also exports the following subroutines for use in dispatchers:
120 response_filter { ... };
122 redispatch_to '/somewhere';
126 $INC{"NameOfApplication.pm"} = 'Set by "use Web::Simple;" invocation';
128 so that perl will not attempt to load the application again even if
130 require NameOfApplication;
132 is encountered in other code.
134 One important thing to remember when using
136 NameOfApplication->run_if_script;
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
142 NameOfApplication->run_request_if_script_else_turn_coderef_for_psgi;
144 =head1 DISPATCH STRATEGY
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.
154 sub dispatch_request {
156 # matches: GET /user/1.htm?show_details=1
158 'GET + /user/* + ?show_details~ + .htm|.html|.xhtml' => sub {
159 my ($self, $user_id, $show_details) = @_;
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) = @_;
168 # matches: DELETE /user/1/friend/2
169 'DELETE + /user/*/friend/*' => sub {
170 my ($self, $user_id, $friend_id) = @_;
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) = @_;
178 '/user/*/...' => sub {
181 # matches: PUT /user/1/role/1
182 'PUT + /role/*' => sub {
186 # matches: DELETE /user/1/role/1
187 'DELETE + /role/*' => sub {
196 =head2 The dispatch cycle
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:
202 sub dispatch_request {
203 my ($self, $env) = @_;
204 [ 404, [ 'Content-type' => 'text/plain' ], [ 'Amnesia == fail' ] ]
207 However, generally, instead of that, you return a set of route/target
210 sub dispatch_request {
213 '/' => sub { redispatch_to '/index.html' },
214 '/user/*' => sub { $self->show_user($_[1]) },
215 'POST + %*' => 'handle_post',
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
224 sub dispatch_request {
227 # This is pure PSGI here, so read perldoc PSGI
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).
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.
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:
242 sub dispatch_request {
245 '.html' => sub { response_filter { $self->render_zoom($_[0]) } },
246 '/user/*' => sub { $self->users->get($_[1]) },
250 An alternative to using string + suborutine to declare a route is to use
253 sub dispatch_request {
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 (...) {'
262 This can be useful sugar, especially if you want to keep method-based
263 dispatchers' route specifications on the methods.
265 to render a user object to HTML, if there is an incoming URL such as:
267 http://myweb.org/user/111.html
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
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:
280 sub dispatch_request {
283 '/static/...' => sub { Plack::App::File->new(...) },
288 A L<Plack::Middleware> object will be used as a filter for the rest of the
289 dispatch being returned into:
291 ## responds to /admin/track_usage AND /admin/delete_accounts
293 sub dispatch_request {
297 Plack::Middleware::Session->new(%opts);
299 '/admin/track_usage' => sub {
300 ## something that needs a session
302 '/admin/delete_accounts' => sub {
303 ## something else that needs a session
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:
311 ## ALSO responds to /admin/track_usage AND /admin/delete_accounts
313 sub dispatch_request {
316 '/admin/...' => sub {
319 Plack::Middleware::Session->new(%opts);
321 '/track_usage' => sub {
322 ## something that needs a session
324 '/delete_accounts' => sub {
325 ## something else that needs a session
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>.
336 =head2 Web::Simple match specifications
338 =head3 Method matches
342 A match specification beginning with a capital letter matches HTTP requests
343 with that request method.
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
354 $self->handle_user($_[1])
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:
361 my ($self, $user_1, $user_2) = @_;
363 '/domain/*/user/*' => sub {
364 my ($self, $domain, $user) = @_;
366 and so on. To match an arbitrary number of parts, use C<**>:
369 my ($self, $match) = @_;
371 This will result in a single element for the entire match. Note that you can do
373 '/page/**/edit' => sub {
375 to match an arbitrary number of parts up to but not including some final
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.:
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"
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
396 Note that the '...' is a "maybe something here, maybe not" so the above
397 specification will match like this:
400 /foo/ # match and strip path to '/'
401 /foo/bar/baz # match and strip path to '/bar/baz'
407 Will match on C</foo/bar/baz>, but also include C</foo>. Otherwise it
408 operates the same way as C</foo/...>.
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'
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:
419 '/foo' => sub { 'I match /foo' },
422 '/bar' => sub { 'I match /foo/bar' },
423 '/*' => sub { 'I match /foo/{id}' },
431 '~' => sub { 'I match /foo' },
432 '/bar' => sub { 'I match /foo/bar' },
433 '/*' => sub { 'I match /foo/{id}' },
437 You may prefer the latter example should you wish to take advantage of
438 subdispatchers to scope common activities. For example:
441 my $user_rs = $schema->resultset('User');
443 '~' => sub { $user_rs },
444 '/*' => sub { $user_rs->find($_[1]) },
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.
451 =head4 Naming your patch matches
453 Any C<*>, C<**>, C<*.*>, or C<**.*> match can be followed with C<:name> to make it into a named
456 '/*:one/*:two/*:three/*:four' => sub {
457 "I match /1/2/3/4 capturing { one => 1, two => 2, three => 3, four => 4 }"
460 '/**.*:allofit' => sub {
461 "I match anything capturing { allofit => \$whole_path }"
464 In the specific case of a simple single-* match, the * may be omitted, to
467 '/:one/:two/:three/:four' => sub {
468 "I match /1/2/3/4 capturing { one => 1, two => 2, three => 3, four => 4 }"
471 =head4 C</foo> and C</foo/> are different specs
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:
478 <a href="bar">bar</a>
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>.
484 This makes it necessary to be explicit about the trailing slash.
486 =head3 Extension matches
490 will match .html from the path (assuming the subroutine itself returns
491 something, of course). This is normally used for rendering - e.g.:
494 response_filter { $self->render_html($_[1]) }
501 will match any extension and supplies the extension as a match argument.
503 =head3 Query and body parameter matches
505 Query and body parameters can be match via
507 '?<param spec>' => sub { # match URI query
508 '%<param spec>' => sub { # match body params
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.
514 The param spec is elements of one of the following forms:
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
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.
531 Please note that if you specify a multiple type parameter match, you are
532 ensured of getting an arrayref for the value, EVEN if the current incoming
533 request has only one value. However if a parameter is specified as single
534 and multiple values are found, the last one will be used.
536 For example to match a C<page> parameter with an optional C<order_by> parameter one
539 '?page=&order_by~' => sub {
540 my ($self, $page, $order_by) = @_;
541 return unless $page =~ /^\d+$/;
544 $_[1]->search_rs({}, { page => $page, order_by => $order_by });
548 to implement paging and ordering against a L<DBIx::Class::ResultSet> object.
550 Another Example: To get all parameters as a hashref of arrayrefs, write:
553 my ($self, $params) = @_;
556 To get two parameters as a hashref, write:
558 '?:user~&:domain~' => sub {
559 my ($self, $params) = @_; # params contains only 'user' and 'domain' keys
561 You can also mix these, so:
563 '?foo=&@bar~&:coffee=&@*' => sub {
564 my ($self, $foo, $bar, $params) = @_;
566 where $bar is an arrayref (possibly an empty one), and $params contains
567 arrayref values for all parameters B<not> mentioned and a scalar value for
568 the 'coffee' parameter.
570 Note, in the case where you combine arrayref, single parameter and named
571 hashref style, the arrayref and single parameters will appear in C<@_> in the
572 order you defined them in the protoype, but all hashrefs will merge into a
573 single C<$params>, as in the example above.
575 =head3 Upload matches
577 '*foo=' => sub { # param specifier can be anything valid for query or body
579 The upload match system functions exactly like a query/body match, except
580 that the values returned (if any) are C<Web::Dispatch::Upload> objects.
582 Note that this match type will succeed in two circumstances where you might
583 not expect it to - first, when the field exists but is not an upload field
584 and second, when the field exists but the form is not an upload form (i.e.
585 content type "application/x-www-form-urlencoded" rather than
586 "multipart/form-data"). In either of these cases, what you'll get back is
587 a C<Web::Dispatch::NotAnUpload> object, which will C<die> with an error
588 pointing out the problem if you try and use it. To be sure you have a real
591 $upload->is_upload # returns 1 on a valid upload, 0 on a non-upload field
593 and to get the reason why such an object is not an upload, call
595 $upload->reason # returns a reason or '' on a valid upload.
597 Other than these two methods, the upload object provides the same interface
598 as L<Plack::Request::Upload> with the addition of a stringify to the temporary
599 filename to make copying it somewhere else easier to handle.
601 =head3 Combining matches
603 Matches may be combined with the + character - e.g.
605 'GET + /user/*' => sub {
607 to create an AND match. They may also be combined withe the | character - e.g.
611 to create an OR match. Matches can be nested with () - e.g.
613 '(GET|POST + /user/*)' => sub {
615 and negated with ! - e.g.
617 '!/user/foo + /user/*' => sub {
619 ! binds to the immediate rightmost match specification, so if you want
620 to negate a combination you will need to use
622 '!(POST|PUT|DELETE)' => sub {
624 and | binds tighter than +, so
626 '(GET|POST) + /user/*' => sub {
630 'GET|POST + /user/*' => sub {
634 '(GET + /admin/...) | (POST + /admin/...)' => sub {
638 'GET + /admin/... | POST + /admin/...' => sub {
640 are not - the latter is equivalent to
642 'GET + (/admin/...|POST) + /admin/...' => sub {
644 which will never match!
648 Note that for legibility you are permitted to use whitespace:
650 'GET + /user/*' => sub {
652 but it will be ignored. This is because the perl parser strips whitespace
653 from subroutine prototypes, so this is equivalent to
655 'GET+/user/*' => sub {
657 =head3 Accessing parameters via C<%_>
659 If your dispatch specification causes your dispatch subroutine to receive
660 a hash reference as its first argument, the contained named parameters
661 will be accessible via C<%_>.
663 This can be used to access your path matches, if they are named:
665 'GET + /foo/:path_part' => sub {
667 ['Content-type' => 'text/plain'],
668 ["We are in $_{path_part}"],
672 Or, if your first argument would be a hash reference containing named
675 'GET + /foo + ?:some_param=' => sub {
677 ['Content-type' => 'text/plain'],
678 ["We received $_{some_param} as parameter"],
682 Of course this also works when all you are doing is slurping the whole set
683 of parameters by their name:
685 'GET + /foo + ?*' => sub {
687 ['Content-type' => 'text/plain'],
688 [exists($_{foo}) ? "Received a foo: $_{foo}" : "No foo!"],
692 Note that only the first hash reference will be available via C<%_>. If
693 you receive additional hash references, you will need to access them as
696 =head3 Accessing the PSGI env hash
698 In some cases you may wish to get the raw PSGI env hash - to do this,
699 you can either use a plain sub:
706 or use the C<PSGI_ENV> constant exported to retrieve it from C<@_>:
708 'GET + /foo + ?some_param=' => sub {
710 my $env = $_[PSGI_ENV];
713 but note that if you're trying to add a middleware, you should simply use
714 Web::Simple's direct support for doing so.
716 =head1 EXPORTED SUBROUTINES
718 =head2 response_filter
721 # Hide errors from the user because we hates them, preciousss
722 if (ref($_[0]) eq 'ARRAY' && $_[0]->[0] == 500) {
723 $_[0] = [ 200, @{$_[0]}[1..$#{$_[0]}] ];
728 The response_filter subroutine is designed for use inside dispatch subroutines.
730 It creates and returns a special dispatcher that always matches, and calls
731 the block passed to it as a filter on the result of running the rest of the
732 current dispatch chain.
734 Thus the filter above runs further dispatch as normal, but if the result of
735 dispatch is a 500 (Internal Server Error) response, changes this to a 200 (OK)
736 response without altering the headers or body.
740 redispatch_to '/other/url';
742 The redispatch_to subroutine is designed for use inside dispatch subroutines.
744 It creates and returns a special dispatcher that always matches, and instead
745 of continuing dispatch re-delegates it to the start of the dispatch process,
746 but with the path of the request altered to the supplied URL.
748 Thus if you receive a POST to C</some/url> and return a redispatch to
749 C</other/url>, the dispatch behaviour will be exactly as if the same POST
750 request had been made to C</other/url> instead.
752 Note, this is not the same as returning an HTTP 3xx redirect as a response;
753 rather it is a much more efficient internal process.
755 =head1 CHANGES BETWEEN RELEASES
757 =head2 Changes between 0.004 and 0.005
761 =item * dispatch {} replaced by declaring a dispatch_request method
763 dispatch {} has gone away - instead, you write:
765 sub dispatch_request {
768 'GET /foo/' => sub { ... },
773 Note that this method is still B<returning> the dispatch code - just like
776 Also note that you need the C<< my $self = shift >> since the magic $self
779 =item * the magic $self variable went away.
781 Just add C<< my $self = shift; >> while writing your C<< sub dispatch_request { >>
782 like a normal perl method.
784 =item * subdispatch deleted - all dispatchers can now subdispatch
786 In earlier releases you needed to write:
788 subdispatch sub (/foo/...) {
791 sub (GET /bar/) { ... },
796 As of 0.005, you can instead write simply:
801 sub (GET /bar/) { ... },
808 =head2 Changes since Antiquated Perl
812 =item * filter_response renamed to response_filter
814 This is a pure rename; a global search and replace should fix it.
816 =item * dispatch [] changed to dispatch {}
820 dispatch [ sub(...) { ... }, ... ];
824 dispatch { sub(...) { ... }, ... };
830 =head1 DEVELOPMENT HISTORY
832 Web::Simple was originally written to form part of my Antiquated Perl talk for
833 Italian Perl Workshop 2009, but in writing the bloggery example I realised
834 that having a bare minimum system for writing web applications that doesn't
835 drive me insane was rather nice and decided to spend my attempt at nanowrimo
836 for 2009 improving and documenting it to the point where others could use it.
838 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
839 L<Web::Simple::AntiquatedPerl>.
841 =head1 COMMUNITY AND SUPPORT
845 irc.perl.org #web-simple
847 =head2 No mailing list yet
849 Because mst's non-work email is a bombsite so he'd never read it anyway.
851 =head2 Git repository
853 Gitweb is on http://git.shadowcat.co.uk/ and the clone URL is:
855 git clone git://git.shadowcat.co.uk/catagits/Web-Simple.git
859 Matt S. Trout (mst) <mst@shadowcat.co.uk>
863 Devin Austin (dhoss) <dhoss@cpan.org>
865 Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
867 gregor herrmann (gregoa) <gregoa@debian.org>
869 John Napiorkowski (jnap) <jjn1056@yahoo.com>
871 Josh McMichael <jmcmicha@linus222.gsc.wustl.edu>
873 Justin Hunter (arcanez) <justin.d.hunter@gmail.com>
875 Kjetil Kjernsmo <kjetil@kjernsmo.net>
877 markie <markie@nulletch64.dreamhost.com>
879 Christian Walde (Mithaldu) <walde.christian@googlemail.com>
881 nperez <nperez@cpan.org>
883 Robin Edwards <robin.ge@gmail.com>
885 Andrew Rodland (hobbs) <andrew@cleverdomain.org>
887 Robert Sedlacek (phaylon) <r.sedlacek@shadowcat.co.uk>
889 Hakim Cassimally (osfameron) <osfameron@cpan.org>
891 Karen Etheridge (ether) <ether@cpan.org>
895 Copyright (c) 2011 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
900 This library is free software and may be distributed under the same terms