5 use warnings::illegalproto ();
7 use Web::Dispatch::Wrapper ();
9 our $VERSION = '0.004';
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
39 This is really quite new. If you're reading this on CPAN, it means the stuff
40 that's here we're probably happy with. But only probably. So we may have to
41 change stuff. And if you're reading this from git, come check with irc.perl.org
42 #web-simple that we're actually sure we're going to keep anything that's
43 different from the CPAN version.
45 If we do find we have to change stuff we'll add to the
46 L<CHANGES BETWEEN RELEASES> section explaining how to switch your code across
47 to the new version, and we'll do our best to make it as painless as possible
48 because we've got Web::Simple applications too. But we can't promise not to
49 change things at all. Not yet. Sorry.
55 use Web::Simple 'HelloWorld';
60 sub dispatch_request {
62 [ 200, [ 'Content-type', 'text/plain' ], [ 'Hello world!' ] ]
65 [ 405, [ 'Content-type', 'text/plain' ], [ 'Method not allowed' ] ]
70 HelloWorld->run_if_script;
72 If you save this file into your cgi-bin as hello-world.cgi and then visit
74 http://my.server.name/cgi-bin/hello-world.cgi/
76 you'll get the "Hello world!" string output to your browser. For more complex
77 examples and non-CGI deployment, see below. To get help with Web::Simple,
78 please connect to the irc.perl.org IRC network and join #web-simple.
82 Web::Simple was originally written to form part of my Antiquated Perl talk for
83 Italian Perl Workshop 2009, but in writing the bloggery example I realised
84 that having a bare minimum system for writing web applications that doesn't
85 drive me insane was rather nice and decided to spend my attempt at nanowrimo
86 for 2009 improving and documenting it to the point where others could use it.
88 The philosophy of Web::Simple is to keep to an absolute bare minimum, for
89 everything. It is not designed to be used for large scale applications;
90 the L<Catalyst> web framework already works very nicely for that and is
91 a far more mature, well supported piece of software.
93 However, if you have an application that only does a couple of things, and
94 want to not have to think about complexities of deployment, then Web::Simple
95 might be just the thing for you.
97 The Antiquated Perl talk can be found at L<http://www.shadowcat.co.uk/archive/conference-video/>.
101 The only public interface the Web::Simple module itself provides is an
104 use Web::Simple 'NameOfApplication';
106 This imports 'strict' and 'warnings FATAL => "all"' into your code as well,
107 so you can skip the usual
112 provided you 'use Web::Simple' at the top of the file. Note that we turn
113 on *fatal* warnings so if you have any warnings at any point from the file
114 that you did 'use Web::Simple' in, then your application will die. This is,
115 so far, considered a feature.
117 Calling the import also makes NameOfApplication isa Web::Simple::Application
118 and sets your app class up as a L<Moo> class- i.e. does the equivalent of
121 package NameOfApplication;
123 extends 'Web::Simple::Application';
126 It also exports the following subroutines for use in dispatchers:
128 response_filter { ... };
130 redispatch_to '/somewhere';
134 $INC{"NameOfApplication.pm"} = 'Set by "use Web::Simple;" invocation';
136 so that perl will not attempt to load the application again even if
138 require NameOfApplication;
140 is encountered in other code.
142 =head1 DISPATCH STRATEGY
146 sub dispatch_request {
147 # matches: GET /user/1.htm?show_details=1
149 sub (GET + /user/* + ?show_details~ + .htm|.html|.xhtml) {
150 my ($self, $user_id, $show_details) = @_;
153 # matches: POST /user?username=frew
154 # POST /user?username=mst&first_name=matt&last_name=trout
155 sub (POST + /user + ?username=&*) {
156 my ($self, $username, $misc_params) = @_;
159 # matches: DELETE /user/1/friend/2
160 sub (DELETE + /user/*/friend/*) {
161 my ($self, $user_id, $friend_id) = @_;
164 # matches: PUT /user/1?first_name=Matt&last_name=Trout
165 sub (PUT + /user/* + ?first_name~&last_name~) {
166 my ($self, $user_id, $first_name, $last_name) = @_;
171 # matches: PUT /user/1/role/1
172 sub (PUT + /role/*) {
176 # matches: DELETE /user/1/role/1
177 sub (DELETE + /role/*) {
184 =head2 The dispatch cycle
186 At the beginning of a request, your app's dispatch_request method is called
187 with the PSGI $env as an argument. You can handle the request entirely in
188 here and return a PSGI response arrayref if you want:
190 sub dispatch_request {
191 my ($self, $env) = @_;
192 [ 404, [ 'Content-type' => 'text/plain' ], [ 'Amnesia == fail' ] ]
195 However, generally, instead of that, you return a set of dispatch subs:
197 sub dispatch_request {
199 sub (/) { redispatch_to '/index.html' },
200 sub (/user/*) { $self->show_user($_[1]) },
204 If you return a subroutine with a prototype, the prototype is treated
205 as a match specification - and if the test is passed, the body of the
206 sub is called as a method any matched arguments (see below for more details).
208 You can also return a plain subroutine which will be called with just $env
209 - remember that in this case if you need $self you -must- close over it.
211 If you return a normal object, Web::Simple will simply return it upwards on
212 the assumption that a response_filter somewhere will convert it to something
213 useful - this allows:
215 sub dispatch_request {
217 sub (.html) { response_filter { $self->render_zoom($_[0]) } },
218 sub (/user/*) { $self->users->get($_[1]) },
221 to render a user object to HTML, for example.
223 However, two types of object are treated specially - a Plack::App object
224 will have its ->to_app method called and be used as a dispatcher:
226 sub dispatch_request {
228 sub (/static/...) { Plack::App::File->new(...) },
232 A Plack::Middleware object will be used as a filter for the rest of the
233 dispatch being returned into:
235 sub dispatch_request {
238 sub (/admin) { Plack::Middleware::Session->new(...) },
239 ... # dispatchers needing a session go here
242 Note that this is for the dispatch being -returned- to, so if you want to
243 provide it inline you need to do:
245 sub dispatch_request {
249 sub { Plack::Middleware::Session->new(...) },
250 ... # dispatchers under /admin
254 And that's it - but remember that all this happens recursively - it's
255 dispatchers all the way down.
257 =head2 Web::Simple match specifications
259 =head3 Method matches
263 A match specification beginning with a capital letter matches HTTP requests
264 with that request method.
270 A match specification beginning with a / is a path match. In the simplest
271 case it matches a specific path. To match a path with a wildcard part, you
275 $self->handle_user($_[1])
277 This will match /user/<anything> where <anything> does not include a literal
278 / character. The matched part becomes part of the match arguments. You can
279 also match more than one part:
282 my ($self, $user_1, $user_2) = @_;
284 sub (/domain/*/user/*) {
285 my ($self, $domain, $user) = @_;
287 and so on. To match an arbitrary number of parts, use -
291 This will result in an element per /-separated part so matched. Note that
294 sub (/page/**/edit) {
296 to match an arbitrary number of parts up to but not including some final
303 will match /foo/ on the beginning of the path -and- strip it, much like
304 .html strips the extension. This is designed to be used to construct
305 nested dispatch structures, but can also prove useful for having e.g. an
306 optional language specification at the start of a path.
308 Note that the '...' is a "maybe something here, maybe not" so the above
309 specification will match like this:
312 /foo/ # match and strip path to '/'
313 /foo/bar/baz # match and strip path to '/bar/baz'
315 =head3 Extension matches
319 will match and strip .html from the path (assuming the subroutine itself
320 returns something, of course). This is normally used for rendering - e.g.
323 response_filter { $self->render_html($_[1]) }
330 will match any extension and supplies the stripped extension as a match
333 =head3 Query and body parameter matches
335 Query and body parameters can be match via
337 sub (?<param spec>) { # match URI query
338 sub (%<param spec>) { # match body params
340 The body is only matched if the content type is
341 application/x-www-form-urlencoded (note this means that Web::Simple does
342 not yet handle uploads; this will be addressed in a later release).
344 The param spec is elements of one of the following forms -
346 param~ # optional parameter
347 param= # required parameter
348 @param~ # optional multiple parameter
349 @param= # required multiple parameter
350 :param~ # optional parameter in hashref
351 :param= # required parameter in hashref
352 :@param~ # optional multiple in hashref
353 :@param= # required multiple in hashref
354 * # include all other parameters in hashref
355 @* # include all other parameters as multiple in hashref
357 separated by the & character. The arguments added to the request are
358 one per non-:/* parameter (scalar for normal, arrayref for multiple),
359 plus if any :/* specs exist a hashref containing those values.
361 So, to match a page parameter with an optional order_by parameter one
364 sub (?page=&order_by~) {
365 my ($self, $page, $order_by) = @_;
366 return unless $page =~ /^\d+$/;
369 $_[1]->search_rs({}, $p);
373 to implement paging and ordering against a L<DBIx::Class::ResultSet> object.
375 Note that if a parameter is specified as single and multiple values are found,
376 the last one will be used.
378 To get all parameters as a hashref of arrayrefs, write:
381 my ($self, $params) = @_;
384 To get two parameters as a hashref, write:
386 sub(?:user~&:domain~) {
387 my ($self, $params) = @_; # params contains only 'user' and 'domain' keys
389 You can also mix these, so:
391 sub (?foo=&@bar~&:coffee=&@*) {
392 my ($self, $foo, $bar, $params);
394 where $bar is an arrayref (possibly an empty one), and $params contains
395 arrayref values for all parameters -not- mentioned and a scalar value for
396 the 'coffee' parameter.
398 =head3 Combining matches
400 Matches may be combined with the + character - e.g.
402 sub (GET + /user/*) {
404 to create an AND match. They may also be combined withe the | character - e.g.
408 to create an OR match. Matches can be nested with () - e.g.
410 sub ((GET|POST) + /user/*) {
412 and negated with ! - e.g.
414 sub (!/user/foo + /user/*) {
416 ! binds to the immediate rightmost match specification, so if you want
417 to negate a combination you will need to use
419 sub ( !(POST|PUT|DELETE) ) {
421 and | binds tighter than +, so
423 sub ((GET|POST) + /user/*) {
427 sub (GET|POST + /user/*) {
431 sub ((GET + .html) | (POST + .html)) {
435 sub (GET + .html | POST + .html) {
437 are not - the latter is equivalent to
439 sub (GET + (.html|POST) + .html) {
441 which will never match.
445 Note that for legibility you are permitted to use whitespace -
447 sub (GET + /user/*) {
449 but it will be ignored. This is because the perl parser strips whitespace
450 from subroutine prototypes, so this is equivalent to
454 =head3 Accessing the PSGI env hash
456 In some cases you may wish to get the raw PSGI env hash - to do this,
457 you can either use a plain sub -
464 or use the PSGI_ENV constant exported to retrieve it:
466 sub (GET + /foo + ?some_param=) {
468 my $env = $_[PSGI_ENV];
471 but note that if you're trying to add a middleware, you should simply use
472 Web::Simple's direct support for doing so.
474 =head1 EXPORTED SUBROUTINES
476 =head2 response_filter
479 # Hide errors from the user because we hates them, preciousss
480 if (ref($_[0]) eq 'ARRAY' && $_[0]->[0] == 500) {
481 $_[0] = [ 200, @{$_[0]}[1..$#{$_[0]}] ];
486 The response_filter subroutine is designed for use inside dispatch subroutines.
488 It creates and returns a special dispatcher that always matches, and calls
489 the block passed to it as a filter on the result of running the rest of the
490 current dispatch chain.
492 Thus the filter above runs further dispatch as normal, but if the result of
493 dispatch is a 500 (Internal Server Error) response, changes this to a 200 (OK)
494 response without altering the headers or body.
498 redispatch_to '/other/url';
500 The redispatch_to subroutine is designed for use inside dispatch subroutines.
502 It creates and returns a special dispatcher that always matches, and instead
503 of continuing dispatch re-delegates it to the start of the dispatch process,
504 but with the path of the request altered to the supplied URL.
506 Thus if you receive a POST to '/some/url' and return a redispatch to
507 '/other/url', the dispatch behaviour will be exactly as if the same POST
508 request had been made to '/other/url' instead.
510 =head1 CHANGES BETWEEN RELEASES
512 =head2 Changes between 0.004 and 0.005
516 =item * dispatch {} replaced by declaring a dispatch_request method
518 dispatch {} has gone away - instead, you write:
520 sub dispatch_request {
522 sub (GET /foo/) { ... },
526 Note that this method is still -returning- the dispatch code - just like
529 Also note that you need the 'my $self = shift' since the magic $self
532 =item * the magic $self variable went away.
534 Just add 'my $self = shift;' while writing your 'sub dispatch_request {'
535 like a normal perl method.
537 =item * subdispatch deleted - all dispatchers can now subdispatch
539 In earlier releases you needed to write:
541 subdispatch sub (/foo/...) {
544 sub (GET /bar/) { ... },
549 As of 0.005, you can instead write simply:
554 sub (GET /bar/) { ... },
559 =head2 Changes since Antiquated Perl
563 =item * filter_response renamed to response_filter
565 This is a pure rename; a global search and replace should fix it.
567 =item * dispatch [] changed to dispatch {}
571 dispatch [ sub(...) { ... }, ... ];
575 dispatch { sub(...) { ... }, ... };
581 =head1 COMMUNITY AND SUPPORT
585 irc.perl.org #web-simple
587 =head2 No mailing list yet
589 Because mst's non-work email is a bombsite so he'd never read it anyway.
591 =head2 Git repository
593 Gitweb is on http://git.shadowcat.co.uk/ and the clone URL is:
595 git clone git://git.shadowcat.co.uk/catagits/Web-Simple.git
599 Matt S. Trout <mst@shadowcat.co.uk>
603 None required yet. Maybe this module is perfect (hahahahaha ...).
607 Copyright (c) 2009 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
612 This library is free software and may be distributed under the same terms