5 use warnings::illegalproto ();
7 use Web::Dispatch::Wrapper ();
9 our $VERSION = '0.018';
12 my ($class, $app_package) = @_;
13 $app_package ||= caller;
14 $class->_export_into($app_package);
15 eval "package $app_package; use Web::Dispatch::Wrapper; use Moo; 1"
16 or die "Failed to setup app package: $@";
18 warnings::illegalproto->unimport;
22 my ($class, $app_package) = @_;
25 *{"${app_package}::PSGI_ENV"} = sub () { -1 };
26 require Web::Simple::Application;
27 unshift(@{"${app_package}::ISA"}, 'Web::Simple::Application');
29 (my $name = $app_package) =~ s/::/\//g;
30 $INC{"${name}.pm"} = 'Set by "use Web::Simple;" invocation';
37 Web::Simple - A quick and easy way to build simple web applications
47 sub dispatch_request {
49 [ 200, [ 'Content-type', 'text/plain' ], [ 'Hello world!' ] ]
52 [ 405, [ 'Content-type', 'text/plain' ], [ 'Method not allowed' ] ]
56 HelloWorld->run_if_script;
58 If you save this file into your cgi-bin as C<hello-world.cgi> and then visit:
60 http://my.server.name/cgi-bin/hello-world.cgi/
62 you'll get the "Hello world!" string output to your browser. At the same time
63 this file will also act as a class module, so you can save it as HelloWorld.pm
64 and use it as-is in test scripts or other deployment mechanisms.
66 Note that you should retain the ->run_if_script even if your app is a
67 module, since this additionally makes it valid as a .psgi file, which can
68 be extremely useful during development.
70 For more complex examples and non-CGI deployment, see
71 L<Web::Simple::Deployment>. To get help with L<Web::Simple>, please connect to
72 the irc.perl.org IRC network and join #web-simple.
76 The philosophy of L<Web::Simple> is to keep to an absolute bare minimum for
77 everything. It is not designed to be used for large scale applications;
78 the L<Catalyst> web framework already works very nicely for that and is
79 a far more mature, well supported piece of software.
81 However, if you have an application that only does a couple of things, and
82 want to not have to think about complexities of deployment, then L<Web::Simple>
83 might be just the thing for you.
85 The only public interface the L<Web::Simple> module itself provides is an
88 use Web::Simple 'NameOfApplication';
90 This sets up your package (in this case "NameOfApplication" is your package)
91 so that it inherits from L<Web::Simple::Application> and imports L<strictures>,
92 as well as installs a C<PSGI_ENV> constant for convenience, as well as some
95 Importing L<strictures> will automatically make your code use the C<strict> and
96 C<warnings> pragma, so you can skip the usual:
99 use warnings FATAL => 'aa';
101 provided you 'use Web::Simple' at the top of the file. Note that we turn
102 on *fatal* warnings so if you have any warnings at any point from the file
103 that you did 'use Web::Simple' in, then your application will die. This is,
104 so far, considered a feature.
106 When we inherit from L<Web::Simple::Application> we also use L<Moo>, which is
107 the the equivalent of:
110 package NameOfApplication;
112 extends 'Web::Simple::Application';
115 So you can use L<Moo> features in your application, such as creating attributes
116 using the C<has> subroutine, etc. Please see the documentation for L<Moo> for
119 It also exports the following subroutines for use in dispatchers:
121 response_filter { ... };
123 redispatch_to '/somewhere';
127 $INC{"NameOfApplication.pm"} = 'Set by "use Web::Simple;" invocation';
129 so that perl will not attempt to load the application again even if
131 require NameOfApplication;
133 is encountered in other code.
135 =head1 DISPATCH STRATEGY
137 L<Web::Simple> despite being straightforward to use, has a powerful system
138 for matching all sorts of incoming URLs to one or more subroutines. These
139 subroutines can be simple actions to take for a given URL, or something
140 more complicated, including entire L<Plack> applications, L<Plack::Middleware>
141 and nested subdispatchers.
145 sub dispatch_request {
146 # matches: GET /user/1.htm?show_details=1
148 sub (GET + /user/* + ?show_details~ + .htm|.html|.xhtml) {
149 my ($self, $user_id, $show_details) = @_;
152 # matches: POST /user?username=frew
153 # POST /user?username=mst&first_name=matt&last_name=trout
154 sub (POST + /user + ?username=&*) {
155 my ($self, $username, $misc_params) = @_;
158 # matches: DELETE /user/1/friend/2
159 sub (DELETE + /user/*/friend/*) {
160 my ($self, $user_id, $friend_id) = @_;
163 # matches: PUT /user/1?first_name=Matt&last_name=Trout
164 sub (PUT + /user/* + ?first_name~&last_name~) {
165 my ($self, $user_id, $first_name, $last_name) = @_;
170 # matches: PUT /user/1/role/1
171 sub (PUT + /role/*) {
175 # matches: DELETE /user/1/role/1
176 sub (DELETE + /role/*) {
183 =head2 The dispatch cycle
185 At the beginning of a request, your app's dispatch_request method is called
186 with the PSGI $env as an argument. You can handle the request entirely in
187 here and return a PSGI response arrayref if you want:
189 sub dispatch_request {
190 my ($self, $env) = @_;
191 [ 404, [ 'Content-type' => 'text/plain' ], [ 'Amnesia == fail' ] ]
194 However, generally, instead of that, you return a set of dispatch subs:
196 sub dispatch_request {
198 sub (/) { redispatch_to '/index.html' },
199 sub (/user/*) { $self->show_user($_[1]) },
203 Well, a sub is a valid PSGI response too (for ultimate streaming and async
204 cleverness). If you want to return a PSGI sub you have to wrap it into an
207 sub dispatch_request {
210 # This is pure PSGI here, so read perldoc PSGI
214 If you return a subroutine with a prototype, the prototype is treated
215 as a match specification - and if the test is passed, the body of the
216 sub is called as a method any matched arguments (see below for more details).
218 You can also return a plain subroutine which will be called with just $env
219 - remember that in this case if you need $self you -must- close over it.
221 If you return a normal object, L<Web::Simple> will simply return it upwards on
222 the assumption that a response_filter (or some arbitrary L<Plack::Middleware>)
223 somewhere will convert it to something useful. This allows:
225 sub dispatch_request {
227 sub (.html) { response_filter { $self->render_zoom($_[0]) } },
228 sub (/user/*) { $self->users->get($_[1]) },
231 to render a user object to HTML, if there is an incoming URL such as:
233 http://myweb.org/user/111.html
235 This works because as we descend down the dispachers, we first match
236 C<sub (.html)>, which adds a C<response_filter> (basically a specialized routine
237 that follows the L<Plack::Middleware> specification), and then later we also
238 match C<sub (/user/*)> which gets a user and returns that as the response.
239 This user object 'bubbles up' through all the wrapping middleware until it hits
240 the C<response_filter> we defined, after which the return is converted to a
243 However, two types of object are treated specially - a Plack::App object
244 will have its C<->to_app> method called and be used as a dispatcher:
246 sub dispatch_request {
248 sub (/static/...) { Plack::App::File->new(...) },
252 A Plack::Middleware object will be used as a filter for the rest of the
253 dispatch being returned into:
255 ## responds to /admin/track_usage AND /admin/delete_accounts
257 sub dispatch_request {
260 Plack::Middleware::Session->new(%opts);
262 sub (/admin/track_usage) {
263 ## something that needs a session
265 sub (/admin/delete_accounts) {
266 ## something else that needs a session
270 Note that this is for the dispatch being -returned- to, so if you want to
271 provide it inline you need to do:
273 ## ALSO responds to /admin/track_usage AND /admin/delete_accounts
275 sub dispatch_request {
279 Plack::Middleware::Session->new(%opts);
282 ## something that needs a session
284 sub (/delete_accounts) {
285 ## something else that needs a session
290 And that's it - but remember that all this happens recursively - it's
291 dispatchers all the way down. A URL incoming pattern will run all matching
292 dispatchers and then hit all added filters or L<Plack::Middleware>.
294 =head2 Web::Simple match specifications
296 =head3 Method matches
300 A match specification beginning with a capital letter matches HTTP requests
301 with that request method.
307 A match specification beginning with a / is a path match. In the simplest
308 case it matches a specific path. To match a path with a wildcard part, you
312 $self->handle_user($_[1])
314 This will match /user/<anything> where <anything> does not include a literal
315 / character. The matched part becomes part of the match arguments. You can
316 also match more than one part:
319 my ($self, $user_1, $user_2) = @_;
321 sub (/domain/*/user/*) {
322 my ($self, $domain, $user) = @_;
324 and so on. To match an arbitrary number of parts, use -
327 my ($self, $match) = @_;
329 This will result in a single element for the entire match. Note that you can do
331 sub (/page/**/edit) {
333 to match an arbitrary number of parts up to but not including some final
336 Note: Since Web::Simple handles a concept of file extensions, * and **
337 matchers will not by default match things after a final dot, and this
338 can be modified by using *.* and **.* in the final position, i.e.:
340 /one/* matches /one/two.three and captures "two"
341 /one/*.* matches /one/two.three and captures "two.three"
342 /** matches /one/two.three and captures "one/two"
343 /**.* matches /one/two.three and captures "one/two.three"
349 Will match C</foo/> on the beginning of the path -and- strip it. This is
350 designed to be used to construct nested dispatch structures, but can also prove
351 useful for having e.g. an optional language specification at the start of a
354 Note that the '...' is a "maybe something here, maybe not" so the above
355 specification will match like this:
358 /foo/ # match and strip path to '/'
359 /foo/bar/baz # match and strip path to '/bar/baz'
365 Will match on C</foo/bar/baz>, but also include C</foo>. Otherwise it
366 operates the same way as C</foo/...>.
368 /foo # match and strip path to ''
369 /foo/ # match and strip path to '/'
370 /foo/bar/baz # match and strip path to '/bar/baz'
372 Please note the difference between C<sub(/foo/...)> and C<sub(/foo...)>. In
373 the first case, this is expecting to find something after C</foo> (and fails to
374 match if nothing is found), while in the second case we can match both C</foo>
375 and C</foo/more/to/come>. The following are roughly the same:
377 sub (/foo) { 'I match /foo' },
379 sub (/bar) { 'I match /foo/bar' },
380 sub (/*) { 'I match /foo/{id}' },
386 sub (~) { 'I match /foo' },
387 sub (/bar) { 'I match /foo/bar' },
388 sub (/*) { 'I match /foo/{id}' },
391 You may prefer the latter example should you wish to take advantage of
392 subdispatchers to scope common activities. For example:
395 my $user_rs = $schema->resultset('User');
396 sub (~) { $user_rs },
397 sub (/*) { $user_rs->find($_[1]) },
400 You should note the special case path match C<sub (~)> which is only meaningful
401 when it is contained in this type of path match. It matches to an empty path.
403 =head4 Naming your patch matches
405 Any */**/*.*/**.* match can be followed with :name to make it into a named
408 sub (/*:one/*:two/*:three/*:four) {
409 "I match /1/2/3/4 capturing { one => 1, two => 2, three => 3, four => 4 }"
412 sub (/**.*:allofit) {
413 "I match anything capturing { allofit => \$whole_path }"
416 In the specific case of a simple single-* match, the * may be omitted, to
419 sub (/:one/:two/:three/:four) {
420 "I match /1/2/3/4 capturing { one => 1, two => 2, three => 3, four => 4 }"
423 =head4 C</foo> and C</foo/> are different specs
425 As you may have noticed with the difference between C<sub(/foo/...)> and
426 C<sub(/foo...)>, trailing slashes in path specs are significant. This is
427 intentional and necessary to retain the ability to use relative links on
428 websites. Let's demonstrate on this link:
430 <a href="bar">bar</a>
432 If the user loads the url C</foo/> and clicks on this link, they will be
433 sent to C</foo/bar>. However when they are on the url C</foo> and click this
434 link, then they will be sent to C</bar>.
436 This makes it necessary to be explicit about the trailing slash.
438 =head3 Extension matches
442 will match .html from the path (assuming the subroutine itself returns
443 something, of course). This is normally used for rendering - e.g.
446 response_filter { $self->render_html($_[1]) }
453 will match any extension and supplies the extension as a match argument.
455 =head3 Query and body parameter matches
457 Query and body parameters can be match via
459 sub (?<param spec>) { # match URI query
460 sub (%<param spec>) { # match body params
462 The body spec will match if the request content is either
463 application/x-www-form-urlencoded or multipart/form-data - the latter
464 of which is required for uploads, which are now handled experimentally
467 The param spec is elements of one of the following forms -
469 param~ # optional parameter
470 param= # required parameter
471 @param~ # optional multiple parameter
472 @param= # required multiple parameter
473 :param~ # optional parameter in hashref
474 :param= # required parameter in hashref
475 :@param~ # optional multiple in hashref
476 :@param= # required multiple in hashref
477 * # include all other parameters in hashref
478 @* # include all other parameters as multiple in hashref
480 separated by the & character. The arguments added to the request are
481 one per non-:/* parameter (scalar for normal, arrayref for multiple),
482 plus if any :/* specs exist a hashref containing those values.
484 Please note that if you specify a multiple type parameter match, you are
485 ensured of getting an arrayref for the value, EVEN if the current incoming
486 request has only one value. However if a parameter is specified as single
487 and multiple values are found, the last one will be used.
489 For example to match a page parameter with an optional order_by parameter one
492 sub (?page=&order_by~) {
493 my ($self, $page, $order_by) = @_;
494 return unless $page =~ /^\d+$/;
497 $_[1]->search_rs({}, $p);
501 to implement paging and ordering against a L<DBIx::Class::ResultSet> object.
503 Another Example: To get all parameters as a hashref of arrayrefs, write:
506 my ($self, $params) = @_;
509 To get two parameters as a hashref, write:
511 sub(?:user~&:domain~) {
512 my ($self, $params) = @_; # params contains only 'user' and 'domain' keys
514 You can also mix these, so:
516 sub (?foo=&@bar~&:coffee=&@*) {
517 my ($self, $foo, $bar, $params);
519 where $bar is an arrayref (possibly an empty one), and $params contains
520 arrayref values for all parameters -not- mentioned and a scalar value for
521 the 'coffee' parameter.
523 Note, in the case where you combine arrayref, single parameter and named
524 hashref style, the arrayref and single parameters will appear in C<@_> in the
525 order you defined them in the protoype, but all hashrefs will merge into a
526 single C<$params>, as in the example above.
528 =head3 Upload matches
530 sub (*foo=) { # param specifier can be anything valid for query or body
532 The upload match system functions exactly like a query/body match, except
533 that the values returned (if any) are C<Web::Dispatch::Upload> objects.
535 Note that this match type will succeed in two circumstances where you might
536 not expect it to - first, when the field exists but is not an upload field
537 and second, when the field exists but the form is not an upload form (i.e.
538 content type "application/x-www-form-urlencoded" rather than
539 "multipart/form-data"). In either of these cases, what you'll get back is
540 a C<Web::Dispatch::NotAnUpload> object, which will C<die> with an error
541 pointing out the problem if you try and use it. To be sure you have a real
544 $upload->is_upload # returns 1 on a valid upload, 0 on a non-upload field
546 and to get the reason why such an object is not an upload, call
548 $upload->reason # returns a reason or '' on a valid upload.
550 Other than these two methods, the upload object provides the same interface
551 as L<Plack::Request::Upload> with the addition of a stringify to the temporary
552 filename to make copying it somewhere else easier to handle.
554 =head3 Combining matches
556 Matches may be combined with the + character - e.g.
558 sub (GET + /user/*) {
560 to create an AND match. They may also be combined withe the | character - e.g.
564 to create an OR match. Matches can be nested with () - e.g.
566 sub ((GET|POST) + /user/*) {
568 and negated with ! - e.g.
570 sub (!/user/foo + /user/*) {
572 ! binds to the immediate rightmost match specification, so if you want
573 to negate a combination you will need to use
575 sub ( !(POST|PUT|DELETE) ) {
577 and | binds tighter than +, so
579 sub ((GET|POST) + /user/*) {
583 sub (GET|POST + /user/*) {
587 sub ((GET + /admin/...) | (POST + /admin/...)) {
591 sub (GET + /admin/... | POST + /admin/...) {
593 are not - the latter is equivalent to
595 sub (GET + (/admin/...|POST) + /admin/...) {
597 which will never match!
601 Note that for legibility you are permitted to use whitespace -
603 sub (GET + /user/*) {
605 but it will be ignored. This is because the perl parser strips whitespace
606 from subroutine prototypes, so this is equivalent to
610 =head3 Accessing the PSGI env hash
612 In some cases you may wish to get the raw PSGI env hash - to do this,
613 you can either use a plain sub -
620 or use the PSGI_ENV constant exported to retrieve it:
622 sub (GET + /foo + ?some_param=) {
624 my $env = $_[PSGI_ENV];
627 but note that if you're trying to add a middleware, you should simply use
628 Web::Simple's direct support for doing so.
630 =head1 EXPORTED SUBROUTINES
632 =head2 response_filter
635 # Hide errors from the user because we hates them, preciousss
636 if (ref($_[0]) eq 'ARRAY' && $_[0]->[0] == 500) {
637 $_[0] = [ 200, @{$_[0]}[1..$#{$_[0]}] ];
642 The response_filter subroutine is designed for use inside dispatch subroutines.
644 It creates and returns a special dispatcher that always matches, and calls
645 the block passed to it as a filter on the result of running the rest of the
646 current dispatch chain.
648 Thus the filter above runs further dispatch as normal, but if the result of
649 dispatch is a 500 (Internal Server Error) response, changes this to a 200 (OK)
650 response without altering the headers or body.
654 redispatch_to '/other/url';
656 The redispatch_to subroutine is designed for use inside dispatch subroutines.
658 It creates and returns a special dispatcher that always matches, and instead
659 of continuing dispatch re-delegates it to the start of the dispatch process,
660 but with the path of the request altered to the supplied URL.
662 Thus if you receive a POST to '/some/url' and return a redispatch to
663 '/other/url', the dispatch behaviour will be exactly as if the same POST
664 request had been made to '/other/url' instead.
666 Note, this is not the same as returning an HTTP 3xx redirect as a response;
667 rather it is a much more efficient internal process.
669 =head1 CHANGES BETWEEN RELEASES
671 =head2 Changes between 0.004 and 0.005
675 =item * dispatch {} replaced by declaring a dispatch_request method
677 dispatch {} has gone away - instead, you write:
679 sub dispatch_request {
681 sub (GET /foo/) { ... },
685 Note that this method is still -returning- the dispatch code - just like
688 Also note that you need the 'my $self = shift' since the magic $self
691 =item * the magic $self variable went away.
693 Just add 'my $self = shift;' while writing your 'sub dispatch_request {'
694 like a normal perl method.
696 =item * subdispatch deleted - all dispatchers can now subdispatch
698 In earlier releases you needed to write:
700 subdispatch sub (/foo/...) {
703 sub (GET /bar/) { ... },
708 As of 0.005, you can instead write simply:
713 sub (GET /bar/) { ... },
720 =head2 Changes since Antiquated Perl
724 =item * filter_response renamed to response_filter
726 This is a pure rename; a global search and replace should fix it.
728 =item * dispatch [] changed to dispatch {}
732 dispatch [ sub(...) { ... }, ... ];
736 dispatch { sub(...) { ... }, ... };
742 =head1 DEVELOPMENT HISTORY
744 Web::Simple was originally written to form part of my Antiquated Perl talk for
745 Italian Perl Workshop 2009, but in writing the bloggery example I realised
746 that having a bare minimum system for writing web applications that doesn't
747 drive me insane was rather nice and decided to spend my attempt at nanowrimo
748 for 2009 improving and documenting it to the point where others could use it.
750 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
751 L<Web::Simple::AntiquatedPerl>.
753 =head1 COMMUNITY AND SUPPORT
757 irc.perl.org #web-simple
759 =head2 No mailing list yet
761 Because mst's non-work email is a bombsite so he'd never read it anyway.
763 =head2 Git repository
765 Gitweb is on http://git.shadowcat.co.uk/ and the clone URL is:
767 git clone git://git.shadowcat.co.uk/catagits/Web-Simple.git
771 Matt S. Trout (mst) <mst@shadowcat.co.uk>
775 Devin Austin (dhoss) <dhoss@cpan.org>
777 Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
779 gregor herrmann (gregoa) <gregoa@debian.org>
781 John Napiorkowski (jnap) <jjn1056@yahoo.com>
783 Josh McMichael <jmcmicha@linus222.gsc.wustl.edu>
785 Justin Hunter (arcanez) <justin.d.hunter@gmail.com>
787 Kjetil Kjernsmo <kjetil@kjernsmo.net>
789 markie <markie@nulletch64.dreamhost.com>
791 Christian Walde (Mithaldu) <walde.christian@googlemail.com>
793 nperez <nperez@cpan.org>
795 Robin Edwards <robin.ge@gmail.com>
797 Andrew Rodland (hobbs) <andrew@cleverdomain.org>
801 Copyright (c) 2011 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
806 This library is free software and may be distributed under the same terms