5 use warnings::illegalproto ();
7 use Web::Dispatch::Wrapper ();
9 our $VERSION = '0.009';
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';
35 Web::Simple - A quick and easy way to build simple web applications
42 use Web::Simple 'HelloWorld';
47 sub dispatch_request {
49 [ 200, [ 'Content-type', 'text/plain' ], [ 'Hello world!' ] ]
52 [ 405, [ 'Content-type', 'text/plain' ], [ 'Method not allowed' ] ]
57 HelloWorld->run_if_script;
59 If you save this file into your cgi-bin as C<hello-world.cgi> and then visit:
61 http://my.server.name/cgi-bin/hello-world.cgi/
63 you'll get the "Hello world!" string output to your browser. For more complex
64 examples and non-CGI deployment, see below. To get help with L<Web::Simple>,
65 please connect to the irc.perl.org IRC network and join #web-simple.
69 The philosophy of L<Web::Simple> is to keep to an absolute bare minimum for
70 everything. It is not designed to be used for large scale applications;
71 the L<Catalyst> web framework already works very nicely for that and is
72 a far more mature, well supported piece of software.
74 However, if you have an application that only does a couple of things, and
75 want to not have to think about complexities of deployment, then L<Web::Simple>
76 might be just the thing for you.
78 The only public interface the L<Web::Simple> module itself provides is an
81 use Web::Simple 'NameOfApplication';
83 This sets up your package (in this case "NameOfApplication" is your package)
84 so that it inherits from L<Web::Simple::Application> and imports L<strictures>,
85 as well as installs a C<PSGI_ENV> constant for convenience, as well as some
88 Importing L<strictures> will automatically make your code use the C<strict> and
89 C<warnings> pragma, so you can skip the usual:
92 use warnings FATAL => 'aa';
94 provided you 'use Web::Simple' at the top of the file. Note that we turn
95 on *fatal* warnings so if you have any warnings at any point from the file
96 that you did 'use Web::Simple' in, then your application will die. This is,
97 so far, considered a feature.
99 When we inherit from L<Web::Simple::Application> we also use L<Moo>, which is
100 the the equivalent of:
103 package NameOfApplication;
105 extends 'Web::Simple::Application';
108 So you can use L<Moo> features in your application, such as creating attributes
109 using the C<has> subroutine, etc. Please see the documentation for L<Moo> for
112 It also exports the following subroutines for use in dispatchers:
114 response_filter { ... };
116 redispatch_to '/somewhere';
120 $INC{"NameOfApplication.pm"} = 'Set by "use Web::Simple;" invocation';
122 so that perl will not attempt to load the application again even if
124 require NameOfApplication;
126 is encountered in other code.
128 =head1 DISPATCH STRATEGY
130 L<Web::Simple> despite being straightforward to use, has a powerful system
131 for matching all sorts of incoming URLs to one or more subroutines. These
132 subroutines can be simple actions to take for a given URL, or something
133 more complicated, including entire L<Plack> applications, L<Plack::Middleware>
134 and nested subdispatchers.
138 sub dispatch_request {
139 # matches: GET /user/1.htm?show_details=1
141 sub (GET + /user/* + ?show_details~ + .htm|.html|.xhtml) {
142 my ($self, $user_id, $show_details) = @_;
145 # matches: POST /user?username=frew
146 # POST /user?username=mst&first_name=matt&last_name=trout
147 sub (POST + /user + ?username=&*) {
148 my ($self, $username, $misc_params) = @_;
151 # matches: DELETE /user/1/friend/2
152 sub (DELETE + /user/*/friend/*) {
153 my ($self, $user_id, $friend_id) = @_;
156 # matches: PUT /user/1?first_name=Matt&last_name=Trout
157 sub (PUT + /user/* + ?first_name~&last_name~) {
158 my ($self, $user_id, $first_name, $last_name) = @_;
163 # matches: PUT /user/1/role/1
164 sub (PUT + /role/*) {
168 # matches: DELETE /user/1/role/1
169 sub (DELETE + /role/*) {
176 =head2 The dispatch cycle
178 At the beginning of a request, your app's dispatch_request method is called
179 with the PSGI $env as an argument. You can handle the request entirely in
180 here and return a PSGI response arrayref if you want:
182 sub dispatch_request {
183 my ($self, $env) = @_;
184 [ 404, [ 'Content-type' => 'text/plain' ], [ 'Amnesia == fail' ] ]
187 However, generally, instead of that, you return a set of dispatch subs:
189 sub dispatch_request {
191 sub (/) { redispatch_to '/index.html' },
192 sub (/user/*) { $self->show_user($_[1]) },
196 If you return a subroutine with a prototype, the prototype is treated
197 as a match specification - and if the test is passed, the body of the
198 sub is called as a method any matched arguments (see below for more details).
200 You can also return a plain subroutine which will be called with just $env
201 - remember that in this case if you need $self you -must- close over it.
203 If you return a normal object, L<Web::Simple> will simply return it upwards on
204 the assumption that a response_filter (or some arbitrary L<Plack::Middleware>)
205 somewhere will convert it to something useful. This allows:
207 sub dispatch_request {
209 sub (.html) { response_filter { $self->render_zoom($_[0]) } },
210 sub (/user/*) { $self->users->get($_[1]) },
213 to render a user object to HTML, if there is an incoming URL such as:
215 http://myweb.org/user/111.html
217 This works because as we descend down the dispachers, we first match
218 C<sub (.html)>, which adds a C<response_filter> (basically a specialized routine
219 that follows the L<Plack::Middleware> specification), and then later we also
220 match C<sub (/user/*)> which gets a user and returns that as the response.
221 This user object 'bubbles up' through all the wrapping middleware until it hits
222 the C<response_filter> we defined, after which the return is converted to a
225 However, two types of object are treated specially - a Plack::App object
226 will have its C<->to_app> method called and be used as a dispatcher:
228 sub dispatch_request {
230 sub (/static/...) { Plack::App::File->new(...) },
234 A Plack::Middleware object will be used as a filter for the rest of the
235 dispatch being returned into:
237 ## responds to /admin/track_usage AND /admin/delete_accounts
239 sub dispatch_request {
242 Plack::Middleware::Session->new(%opts);
244 sub (/admin/track_usage) {
245 ## something that needs a session
247 sub (/admin/delete_accounts) {
248 ## something else that needs a session
252 Note that this is for the dispatch being -returned- to, so if you want to
253 provide it inline you need to do:
255 ## ALSO responds to /admin/track_usage AND /admin/delete_accounts
257 sub dispatch_request {
261 Plack::Middleware::Session->new(%opts);
264 ## something that needs a session
266 sub (/delete_accounts) {
267 ## something else that needs a session
272 And that's it - but remember that all this happens recursively - it's
273 dispatchers all the way down. A URL incoming pattern will run all matching
274 dispatchers and then hit all added filters or L<Plack::Middleware>.
276 =head2 Web::Simple match specifications
278 =head3 Method matches
282 A match specification beginning with a capital letter matches HTTP requests
283 with that request method.
289 A match specification beginning with a / is a path match. In the simplest
290 case it matches a specific path. To match a path with a wildcard part, you
294 $self->handle_user($_[1])
296 This will match /user/<anything> where <anything> does not include a literal
297 / character. The matched part becomes part of the match arguments. You can
298 also match more than one part:
301 my ($self, $user_1, $user_2) = @_;
303 sub (/domain/*/user/*) {
304 my ($self, $domain, $user) = @_;
306 and so on. To match an arbitrary number of parts, use -
310 This will result in an element per /-separated part so matched. Note that
313 sub (/page/**/edit) {
315 to match an arbitrary number of parts up to but not including some final
322 Will match /foo/ on the beginning of the path -and- strip it. This is designed
323 to be used to construct nested dispatch structures, but can also prove useful
324 for having e.g. an optional language specification at the start of a path.
326 Note that the '...' is a "maybe something here, maybe not" so the above
327 specification will match like this:
330 /foo/ # match and strip path to '/'
331 /foo/bar/baz # match and strip path to '/bar/baz'
333 Note: Since Web::Simple handles a concept of file extensions, * and **
334 matchers will not by default match things after a final dot, and this
335 can be modified by using *.* and **.* in the final position, i.e.:
337 /one/* matches /one/two.three and captures "two"
338 /one/*.* matches /one/two.three and captures "two.three"
339 /** matches /one/two.three and captures "one/two"
340 /**.* matches /one/two.three and captures "one/two.three"
342 =head3 Extension matches
346 will match .html from the path (assuming the subroutine itself returns
347 something, of course). This is normally used for rendering - e.g.
350 response_filter { $self->render_html($_[1]) }
357 will match any extension and supplies the extension as a match argument.
359 =head3 Query and body parameter matches
361 Query and body parameters can be match via
363 sub (?<param spec>) { # match URI query
364 sub (%<param spec>) { # match body params
366 The body spec will match if the request content is either
367 application/x-www-form-urlencoded or multipart/form-data - the latter
368 of which is required for uploads, which are now handled experimentally
371 The param spec is elements of one of the following forms -
373 param~ # optional parameter
374 param= # required parameter
375 @param~ # optional multiple parameter
376 @param= # required multiple parameter
377 :param~ # optional parameter in hashref
378 :param= # required parameter in hashref
379 :@param~ # optional multiple in hashref
380 :@param= # required multiple in hashref
381 * # include all other parameters in hashref
382 @* # include all other parameters as multiple in hashref
384 separated by the & character. The arguments added to the request are
385 one per non-:/* parameter (scalar for normal, arrayref for multiple),
386 plus if any :/* specs exist a hashref containing those values.
388 Please note that if you specify a multiple type parameter match, you are
389 ensured of getting an arrayref for the value, EVEN if the current incoming
390 request has only one value. However if a parameter is specified as single
391 and multiple values are found, the last one will be used.
393 For example to match a page parameter with an optional order_by parameter one
396 sub (?page=&order_by~) {
397 my ($self, $page, $order_by) = @_;
398 return unless $page =~ /^\d+$/;
401 $_[1]->search_rs({}, $p);
405 to implement paging and ordering against a L<DBIx::Class::ResultSet> object.
407 Another Example: To get all parameters as a hashref of arrayrefs, write:
410 my ($self, $params) = @_;
413 To get two parameters as a hashref, write:
415 sub(?:user~&:domain~) {
416 my ($self, $params) = @_; # params contains only 'user' and 'domain' keys
418 You can also mix these, so:
420 sub (?foo=&@bar~&:coffee=&@*) {
421 my ($self, $foo, $bar, $params);
423 where $bar is an arrayref (possibly an empty one), and $params contains
424 arrayref values for all parameters -not- mentioned and a scalar value for
425 the 'coffee' parameter.
427 Note, in the case where you combine arrayref, single parameter and named
428 hashref style, the arrayref and single parameters will appear in C<@_> in the
429 order you defined them in the protoype, but all hashrefs will merge into a
430 single C<$params>, as in the example above.
432 =head3 Upload matches (EXPERIMENTAL)
434 Note: This feature is experimental. This means that it may not remain
435 100% in its current form. If we change it, notes on updating your code
436 will be added to the L</CHANGES BETWEEN RELEASES> section below.
438 sub (*foo=) { # param specifier can be anything valid for query or body
440 The upload match system functions exactly like a query/body match, except
441 that the values returned (if any) are C<Web::Dispatch::Upload> objects.
443 Note that this match type will succeed in two circumstances where you might
444 not expect it to - first, when the field exists but is not an upload field
445 and second, when the field exists but the form is not an upload form (i.e.
446 content type "application/x-www-form-urlencoded" rather than
447 "multipart/form-data"). In either of these cases, what you'll get back is
448 a C<Web::Dispatch::NotAnUpload> object, which will C<die> with an error
449 pointing out the problem if you try and use it. To be sure you have a real
452 $upload->is_upload # returns 1 on a valid upload, 0 on a non-upload field
454 and to get the reason why such an object is not an upload, call
456 $upload->reason # returns a reason or '' on a valid upload.
458 Other than these two methods, the upload object provides the same interface
459 as L<Plack::Request::Upload> with the addition of a stringify to the temporary
460 filename to make copying it somewhere else easier to handle.
462 =head3 Combining matches
464 Matches may be combined with the + character - e.g.
466 sub (GET + /user/*) {
468 to create an AND match. They may also be combined withe the | character - e.g.
472 to create an OR match. Matches can be nested with () - e.g.
474 sub ((GET|POST) + /user/*) {
476 and negated with ! - e.g.
478 sub (!/user/foo + /user/*) {
480 ! binds to the immediate rightmost match specification, so if you want
481 to negate a combination you will need to use
483 sub ( !(POST|PUT|DELETE) ) {
485 and | binds tighter than +, so
487 sub ((GET|POST) + /user/*) {
491 sub (GET|POST + /user/*) {
495 sub ((GET + /admin/...) | (POST + /admin/...)) {
499 sub (GET + /admin/... | POST + /admin/...) {
501 are not - the latter is equivalent to
503 sub (GET + (/admin/...|POST) + /admin/...) {
505 which will never match!
509 Note that for legibility you are permitted to use whitespace -
511 sub (GET + /user/*) {
513 but it will be ignored. This is because the perl parser strips whitespace
514 from subroutine prototypes, so this is equivalent to
518 =head3 Accessing the PSGI env hash
520 In some cases you may wish to get the raw PSGI env hash - to do this,
521 you can either use a plain sub -
528 or use the PSGI_ENV constant exported to retrieve it:
530 sub (GET + /foo + ?some_param=) {
532 my $env = $_[PSGI_ENV];
535 but note that if you're trying to add a middleware, you should simply use
536 Web::Simple's direct support for doing so.
538 =head1 EXPORTED SUBROUTINES
540 =head2 response_filter
543 # Hide errors from the user because we hates them, preciousss
544 if (ref($_[0]) eq 'ARRAY' && $_[0]->[0] == 500) {
545 $_[0] = [ 200, @{$_[0]}[1..$#{$_[0]}] ];
550 The response_filter subroutine is designed for use inside dispatch subroutines.
552 It creates and returns a special dispatcher that always matches, and calls
553 the block passed to it as a filter on the result of running the rest of the
554 current dispatch chain.
556 Thus the filter above runs further dispatch as normal, but if the result of
557 dispatch is a 500 (Internal Server Error) response, changes this to a 200 (OK)
558 response without altering the headers or body.
562 redispatch_to '/other/url';
564 The redispatch_to subroutine is designed for use inside dispatch subroutines.
566 It creates and returns a special dispatcher that always matches, and instead
567 of continuing dispatch re-delegates it to the start of the dispatch process,
568 but with the path of the request altered to the supplied URL.
570 Thus if you receive a POST to '/some/url' and return a redispatch to
571 '/other/url', the dispatch behaviour will be exactly as if the same POST
572 request had been made to '/other/url' instead.
574 Note, this is not the same as returning an HTTP 3xx redirect as a response;
575 rather it is a much more efficient internal process.
577 =head1 CHANGES BETWEEN RELEASES
579 =head2 Changes between 0.004 and 0.005
583 =item * dispatch {} replaced by declaring a dispatch_request method
585 dispatch {} has gone away - instead, you write:
587 sub dispatch_request {
589 sub (GET /foo/) { ... },
593 Note that this method is still -returning- the dispatch code - just like
596 Also note that you need the 'my $self = shift' since the magic $self
599 =item * the magic $self variable went away.
601 Just add 'my $self = shift;' while writing your 'sub dispatch_request {'
602 like a normal perl method.
604 =item * subdispatch deleted - all dispatchers can now subdispatch
606 In earlier releases you needed to write:
608 subdispatch sub (/foo/...) {
611 sub (GET /bar/) { ... },
616 As of 0.005, you can instead write simply:
621 sub (GET /bar/) { ... },
628 =head2 Changes since Antiquated Perl
632 =item * filter_response renamed to response_filter
634 This is a pure rename; a global search and replace should fix it.
636 =item * dispatch [] changed to dispatch {}
640 dispatch [ sub(...) { ... }, ... ];
644 dispatch { sub(...) { ... }, ... };
650 =head1 DEVELOPMENT HISTORY
652 Web::Simple was originally written to form part of my Antiquated Perl talk for
653 Italian Perl Workshop 2009, but in writing the bloggery example I realised
654 that having a bare minimum system for writing web applications that doesn't
655 drive me insane was rather nice and decided to spend my attempt at nanowrimo
656 for 2009 improving and documenting it to the point where others could use it.
658 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
659 L<Web::Simple::AntiquatedPerl>.
661 =head1 COMMUNITY AND SUPPORT
665 irc.perl.org #web-simple
667 =head2 No mailing list yet
669 Because mst's non-work email is a bombsite so he'd never read it anyway.
671 =head2 Git repository
673 Gitweb is on http://git.shadowcat.co.uk/ and the clone URL is:
675 git clone git://git.shadowcat.co.uk/catagits/Web-Simple.git
679 Matt S. Trout (mst) <mst@shadowcat.co.uk>
683 Devin Austin (dhoss) <dhoss@cpan.org>
685 Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
687 gregor herrmann (gregoa) <gregoa@debian.org>
689 John Napiorkowski (jnap) <jjn1056@yahoo.com>
691 Josh McMichael <jmcmicha@linus222.gsc.wustl.edu>
693 Justin Hunter <justin.d.hunter@gmail.com>
695 Kjetil Kjernsmo <kjetil@kjernsmo.net>
697 markie <markie@nulletch64.dreamhost.com>
699 Christian Walde (Mithaldu) <walde.christian@googlemail.com>
701 nperez <nperez@cpan.org>
703 Robin Edwards <robin.ge@gmail.com>
707 Copyright (c) 2010 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
712 This library is free software and may be distributed under the same terms