3 Catalyst::Manual::Intro - Introduction to Catalyst
7 This is a brief introduction toCatalyst. It explains the most important
8 features of how Catalyst works and shows how to get a simple application
9 up and running quickly. For an introduction (without code) to Catalyst
10 itself, and why you should be using it, see L<Catalyst::Manual::About>.
12 =head2 What is Catalyst?
14 Catalyst is an elegant web application framework, extremely flexible yet
15 extremely simple. It's similar to Ruby on Rails, Spring (Java) and
16 L<Maypole>, upon which it was originally based.
20 Catalyst follows the Model-View-Controller (MVC) design pattern,
21 allowing you to easily separate concerns, like content, presentation,
22 and flow control, into separate modules. This separation allows you to
23 modify code that handles one concern without affecting code that handles
24 the others. Catalyst promotes the re-use of existing Perl modules that
25 already handle common web application concerns well.
27 Here's how the M, V, and C map to those concerns, with examples of
28 well-known Perl modules you may want to use for each.
34 Access and modify content (data). L<Class::DBI>, L<Plucene>, L<Net::LDAP>...
38 Present content to the user. L<Template Toolkit|Template>,
39 L<Mason|HTML::Mason>, L<HTML::Template>...
43 Control the whole request phase, check parameters, dispatch actions, flow
48 If you're unfamiliar with MVC and design patterns, you may want to check
49 out the original book on the subject, I<Design Patterns>, by Gamma,
50 Helm, Johnson, and Vlissides, also known as the Gang of Four (GoF). You
51 can also just Google it. Many, many web application frameworks are
52 based on MVC, including all those listed above.
56 Catalyst is much more flexible than many other frameworks. We'll talk
57 more about this later, but rest assured you can use your favorite Perl
58 modules with Catalyst.
62 =item * B<Multiple Models, Views, and Controllers>
64 To build a Catalyst application, you handle each type of concern inside
65 special modules called L</Components>. Often this code will be very
66 simple, just calling out to Perl modules like those listed above under
67 L</MVC>. Catalyst handles these components in a very flexible way. Use
68 as many Models, Views, and Controllers as you like, using as many
69 different Perl modules as you like, all in the same application. Want to
70 manipulate multiple databases, and retrieve some data via LDAP? No
71 problem. Want to present data from the same Model using L<Template
72 Toolkit|Template> and L<PDF::Template>? Easy.
74 =item * B<Reuseable Components>
76 Not only does Catalyst promote the re-use of already existing Perl
77 modules, it also allows you to re-use your Catalyst components in
78 multiple Catalyst applications.
80 =item * B<Unrestrained URL-to-Action Dispatching>
82 Catalyst allows you to dispatch any URLs to any application L<Actions>,
83 even through regular expressions! Unlike most other frameworks, it
84 doesn't require mod_rewrite or class and method names in URLs.
86 With Catalyst you register your actions and address them directly. For
90 my ( $self, $context ) = @_;
91 $context->response->body('Hello World!');
94 Now http://localhost:3000/hello prints "Hello World!".
96 =item * B<Support for CGI, mod_perl, Apache::Request>
98 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>.
104 The best part is that Catalyst implements all this flexibility in a very
109 =item * B<Building Block Interface>
111 Components interoperate very smoothly. For example, Catalyst
112 automatically makes a L<Context> object available to every
113 component. Via the context, you can access the request object, share
114 data between components, and control the flow of your
115 application. Building a Catalyst application feels a lot like snapping
116 together toy building blocks, and everything just works.
118 =item * B<Component Auto-Discovery>
120 No need to C<use> all of your components. Catalyst automatically finds
123 =item * B<Pre-Built Components for Popular Modules>
125 See L<Catalyst::Model::CDBI> for L<Class::DBI>, or L<Catalyst::View::TT>
126 for L<Template Toolkit|Template>.
128 =item * B<Built-in Test Framework>
130 Catalyst comes with a built-in, lightweight http server and test
131 framework, making it easy to test applications from the command line.
133 =item * B<Helper Scripts>
135 Catalyst provides helper scripts to quickly generate running starter
136 code for components and unit tests. See L<Catalyst::Helper>.
142 Here's how to install Catalyst and get a simple application up and
143 running, using the helper scripts described above.
147 $ perl -MCPAN -e 'install Task::Catalyst'
154 $ script/myapp_create.pl controller Library::Login
158 $ script/myapp_server.pl
160 Now visit these locations with your favorite browser or user agent to see
165 =item http://localhost:3000/
167 =item http://localhost:3000/library/login/
175 Let's see how Catalyst works, by taking a closer look at the components
176 and other parts of a Catalyst application.
178 =head3 Application Class
180 In addition to the Model, View, and Controller components, there's a
181 single class that represents your application itself. This is where you
182 configure your application, load plugins, define application-wide
183 actions, and extend Catalyst.
188 use Catalyst qw/-Debug/;
191 name => 'My Application',
193 # You can put anything else you want in here:
194 my_configuration_variable => 'something',
197 sub default : Private {
198 my ( $self, $context ) = @_;
199 $context->response->body('Catalyst rocks!');
204 For most applications, Catalyst requires you to define only one config
211 Name of your application.
215 Optionally, you can specify a B<root> parameter for templates and static
216 data. If omitted, Catalyst will try to auto-detect the directory's
217 location. You can define as many parameters as you want for plugins or
218 whatever you need. You can access them anywhere in your application via
219 C<$context-E<gt>config-E<gt>{$param_name}>.
223 Catalyst automatically blesses a Context object into your application
224 class and makes it available everywhere in your application. Use the
225 Context to directly interact with Catalyst and glue your L<Components>
226 together. For example, if you need to use the Context from within a
227 Template Toolkit template, it's already there:
229 <h1>Welcome to [% c.config.name %]!</h1>
231 As illustrated in our URL-to-Action dispatching example, the Context is
232 always the second method parameter, behind the Component object
233 reference or class name itself. Previously we called it C<$context> for
234 clarity, but most Catalyst developers just call it C<$c>:
237 my ( $self, $c ) = @_;
238 $c->res->body('Hello World!');
241 The Context contains several important objects:
245 =item * L<Catalyst::Request>
250 The request object contains all kinds of request-specific information, like
251 query parameters, cookies, uploads, headers, and more.
253 $c->req->params->{foo};
254 $c->req->cookies->{sessionid};
255 $c->req->headers->content_type;
258 =item * L<Catalyst::Response>
263 The response is like the request, but contains just response-specific
266 $c->res->body('Hello World');
267 $c->res->status(404);
268 $c->res->redirect('http://oook.de');
270 =item * L<Catalyst::Config>
276 =item * L<Catalyst::Log>
280 $c->log->debug('Something happened');
281 $c->log->info('Something you should know');
286 $c->stash->{foo} = 'bar';
290 The last of these, the stash, is a universal hash for sharing data among
291 application components. For an example, we return to our 'hello' action:
294 my ( $self, $c ) = @_;
295 $c->stash->{message} = 'Hello World!';
296 $c->forward('show_message');
299 sub show_message : Private {
300 my ( $self, $c ) = @_;
301 $c->res->body( $c->stash->{message} );
304 Note that the stash should be used only for passing data in an
305 individual request cycle; it gets cleared at a new request. If you need
306 to maintain more persistent data, use a session.
310 A Catalyst controller is defined by its actions. An action is a sub with
311 a special attribute. You've already seen some examples of actions in
312 this document. The URL (for example http://localhost.3000/foo/bar)
313 consists of two parts, the base (http://localhost:3000/ in this example)
314 and the path (foo/bar). Please note that the trailing slash after the
315 hostname[:port] always belongs to base and not to the action.
317 Catalyst supports several types of actions:
323 package MyApp::Controller::My::Controller;
324 sub bar : Path('foo/bar') { }
326 Literal C<Path> actions will act relative to their current
327 namespace. The above example matches only
328 http://localhost:3000/my/controller/foo/bar. If you start your path with
329 a forward slash, it will match from the root. Example:
331 package MyApp::Controller::My::Controller;
332 sub bar : Path('/foo/bar') { }
334 Matches only http://localhost:3000/foo/bar.
336 package MyApp::Controller::My::Controller;
339 By leaving the C<Path> definition empty, it will match on the namespace
340 root. The above code matches http://localhost:3000/my/controller.
344 sub bar : Regex('^item(\d+)/order(\d+)$') { }
346 Matches any URL that matches the pattern in the action key, e.g.
347 http://localhost:3000/item23/order42. The '' around the regexp is
348 optional, but perltidy likes it. :)
350 Regex matches act globally, i.e. without reference to the namespace from
351 which it is called, so that a C<bar> method in the
352 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
353 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
354 explicitly put this in the regex. To achieve the above, you should
355 consider using a C<LocalRegex> action.
357 =item * B<LocalRegex>
359 sub bar : LocalRegex('^widget(\d+)$') { }
361 LocalRegex actions act locally. If you were to use C<bar> in
362 C<MyApp::Controller::Catalog>, the above example would match urls like
363 http://localhost:3000/catalog/widget23.
365 If you omit the "C<^>" from your regex, then it will match any depth
366 from the controller and not immediately off of the controller name. The
367 following example differs from the above code in that it will match
368 http://localhost:3000/catalog/foo/widget23 as well.
370 package MyApp::Controller::Catalog;
371 sub bar : LocalRegex('widget(\d+)$') { }
373 For both LocalRegex and Regex actions, if you use capturing parentheses
374 to extract values within the matching URL, those values are available in
375 the C<$c-E<gt>req-E<gt>snippets> array. In the above example, "widget23"
376 would capture "23" in the above example, and
377 C<$c-E<gt>req-E<gt>snippets-E<gt>[0]> would be "23". If you want to pass
378 arguments at the end of your URL, you must use regex action keys. See
379 L</URL Path Handling> below.
386 Matches http://localhost:3000/foo. The function name is mapped directly
387 to the application base.
389 =item * B<Namespace-Prefixed>
391 package MyApp::Controller::My::Controller;
394 Matches http://localhost:3000/my/controller/foo.
396 This action type indicates that the matching URL must be prefixed with a
397 modified form of the component's class (package) name. This modified
398 class name excludes the parts that have a pre-defined meaning in
399 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
400 "/", and converts the name to lower case. See L</Components> for a full
401 explanation of the pre-defined meaning of Catalyst component class
406 sub foo : Private { }
408 Matches no URL, and cannot be executed by requesting a URL that
409 corresponds to the action key. Private actions can be executed only
410 inside a Catalyst application, by calling the C<forward> method:
414 See L</Flow Control> for a full explanation of C<forward>. Note that, as
415 discussed there, when forwarding from another component, you must use
416 the absolute path to the method, so that a private C<bar> method in your
417 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
418 from elsewhere, be reached with
419 C<$c-E<gt>forward('/catalog/order/process/bar')>.
423 B<Note:> After seeing these examples, you probably wonder what the point
424 is of defining names for regex and path actions. Actually, every public
425 action is also a private one, so you have one unified way of addressing
426 components in your C<forward>s.
428 =head4 Built-in Private Actions
430 In response to specific application states, Catalyst will automatically
431 call these built-in private actions in your application class:
435 =item * B<default : Private>
437 Called when no other action matches. Could be used, for example, for
438 displaying a generic frontpage for the main app, or an error page for
439 individual controllers.
441 If C<default> isn't acting how you would expect, look at using a
442 L<Literal> C<Path> action (with an empty path string). The difference is
443 that C<Path> takes arguments relative from the namespace and C<default>
444 I<always> takes arguments relative from the root, regardless of what
447 =item * B<index : Private>
449 C<index> is much like C<default> except that it takes no arguments
450 and it is weighted slightly higher in the matching process. It is
451 useful as a static entry point to a controller, e.g. to have a static
452 welcome page. Note that it's also weighted higher than Path.
454 =item * B<begin : Private>
456 Called at the beginning of a request, before any matching actions are
459 =item * B<end : Private>
461 Called at the end of a request, after all matching actions are called.
465 =head4 Built-in actions in controllers/autochaining
467 Package MyApp::Controller::Foo;
468 sub begin : Private { }
469 sub default : Private { }
470 sub auto : Private { }
472 You can define built-in private actions within your controllers as
473 well. The actions will override the ones in less-specific controllers,
474 or your application class. In other words, for each of the three
475 built-in private actions, only one will be run in any request
476 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
477 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
478 and C<MyApp::Controller::Catalog::Order::begin> would override this in
481 In addition to the normal built-in actions, you have a special action
482 for making chains, C<auto>. Such C<auto> actions will be run after any
483 C<begin>, but before your action is processed. Unlike the other
484 built-ins, C<auto> actions I<do not> override each other; they will be
485 called in turn, starting with the application class and going through to
486 the I<most> specific class. I<This is the reverse of the order in which
487 the normal built-ins override each other>.
489 Here are some examples of the order in which the various built-ins
494 =item for a request for C</foo/foo>
498 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
501 =item for a request for C</foo/bar/foo>
503 MyApp::Controller::Foo::Bar::begin
505 MyApp::Controller::Foo::auto
506 MyApp::Controller::Foo::Bar::auto
507 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
508 MyApp::Controller::Foo::Bar::end
512 The C<auto> action is also distinguished by the fact that you can break
513 out of the processing chain by returning 0. If an C<auto> action returns
514 0, any remaining actions will be skipped, except for C<end>. So, for the
515 request above, if the first auto returns false, the chain would look
520 =item for a request for C</foo/bar/foo> where first C<auto> returns
523 MyApp::Controller::Foo::Bar::begin
525 MyApp::Controller::Foo::Bar::end
529 An example of why one might use this is an authentication action: you
530 could set up a C<auto> action to handle authentication in your
531 application class (which will always be called first), and if
532 authentication fails, returning 0 would skip any remaining methods
535 B<Note:> Looking at it another way, C<auto> actions have to return a
536 true value to continue processing! You can also C<die> in the autochain
537 action; in that case, the request will go straight to the finalize
538 stage, without processing further actions.
540 =head4 URL Path Handling
542 You can pass variable arguments as part of the URL path, separated with
543 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
544 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
545 where C<$bar> and C<$baz> may vary:
547 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
549 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
551 sub boo : Path('foo/boo') { .. }
552 sub hoo : Path('foo/boo/hoo') { .. }
554 Catalyst matches actions in most specific to least specific order:
558 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
560 So Catalyst would never mistakenly dispatch the first two URLs to the
563 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
564 still match a URL containing arguments, however the arguments won't be
567 =head4 Parameter Processing
569 Parameters passed in the URL query string are handled with methods in
570 the L<Catalyst::Request> class. The C<param> method is functionally
571 equivalent to the C<param> method of C<CGI.pm> and can be used in
572 modules that require this.
574 # http://localhost:3000/catalog/view/?category=hardware&page=3
575 my $category = $c->req->param('category');
576 my $current_page = $c->req->param('page') || 1;
578 # multiple values for single parameter name
579 my @values = $c->req->param('scrolling_list');
581 # DFV requires a CGI.pm-like input hash
582 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
586 You control the application flow with the C<forward> method, which
587 accepts the key of an action to execute. This can be an action in the
588 same or another Catalyst controller, or a Class name, optionally
589 followed by a method name. After a C<forward>, the control flow will
590 return to the method from which the C<forward> was issued.
592 A C<forward> is similar to a method call. The main differences are that
593 it wraps the call in an C<eval> to allow exception handling; it
594 automatically passes along the context object (C<$c> or C<$context>);
595 and it allows profiling of each call (displayed in the log with
599 my ( $self, $c ) = @_;
600 $c->stash->{message} = 'Hello World!';
601 $c->forward('check_message'); # $c is automatically included
604 sub check_message : Private {
605 my ( $self, $c ) = @_;
606 return unless $c->stash->{message};
607 $c->forward('show_message');
610 sub show_message : Private {
611 my ( $self, $c ) = @_;
612 $c->res->body( $c->stash->{message} );
615 A C<forward> does not create a new request, so your request
616 object (C<$c-E<gt>req>) will remain unchanged. This is a
617 key difference between using C<forward> and issuing a
620 You can pass new arguments to a C<forward> by adding them
621 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
622 will be changed for the duration of the C<forward> only; upon
623 return, the original value of C<$c-E<gt>req-E<gt>args> will
627 my ( $self, $c ) = @_;
628 $c->stash->{message} = 'Hello World!';
629 $c->forward('check_message',[qw/test1/]);
630 # now $c->req->args is back to what it was before
633 sub check_message : Private {
634 my ( $self, $c ) = @_;
635 my $first_argument = $c->req->args[0]; # now = 'test1'
639 As you can see from these examples, you can just use the method name as
640 long as you are referring to methods in the same controller. If you want
641 to forward to a method in another controller, or the main application,
642 you will have to refer to the method by absolute path.
644 $c->forward('/my/controller/action');
645 $c->forward('/default'); # calls default in main application
647 Here are some examples of how to forward to classes and methods.
650 my ( $self, $c ) = @_;
651 $c->forward(qw/MyApp::Model::Hello say_hello/);
655 my ( $self, $c ) = @_;
656 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
659 package MyApp::Model::Hello;
662 my ( $self, $c ) = @_;
663 $c->res->body('Hello World!');
667 my ( $self, $c ) = @_;
668 $c->res->body('Goodbye World!');
671 Note that C<forward> returns to the calling action and continues
672 processing after the action finishes. If you want all further processing
673 in the calling action to stop, use C<detach> instead, which will execute
674 the C<detach>ed action and not return to the calling sub. In both cases,
675 Catalyst will automatically try to call process() if you omit the
680 Catalyst has an uncommonly flexible component system. You can define as many
681 L<Models>, L<Views>, and L<Controllers> as you like.
683 All components must inherit from L<Catalyst::Base>, which provides a simple
684 class structure and some common class methods like C<config> and C<new>
687 package MyApp::Controller::Catalog;
690 use base 'Catalyst::Base';
692 __PACKAGE__->config( foo => 'bar' );
696 You don't have to C<use> or otherwise register Models, Views, and
697 Controllers. Catalyst automatically discovers and instantiates them
698 when you call C<setup> in the main application. All you need to do is
699 put them in directories named for each Component type. Notice that you
700 can use some very terse aliases for each one.
704 =item * B<MyApp/Model/>
708 =item * B<MyApp/View/>
712 =item * B<MyApp/Controller/>
720 To show how to define views, we'll use an already-existing base class for the
721 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
722 inherit from this class:
724 package MyApp::View::TT;
727 use base 'Catalyst::View::TT';
731 (You can also generate this automatically by using the helper script:
733 script/myapp_create.pl view TT TT
735 where the first C<TT> tells the script that the name of the view should
736 be C<TT>, and the second that it should be a Template Toolkit view.)
738 This gives us a process() method and we can now just do
739 $c->forward('MyApp::View::TT') to render our templates. The base class
740 makes process() implicit, so we don't have to say
741 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
744 my ( $self, $c ) = @_;
745 $c->stash->{template} = 'hello.tt';
749 my ( $self, $c ) = @_;
750 $c->forward('MyApp::View::TT');
753 You normally render templates at the end of a request, so it's a perfect
754 use for the global C<end> action.
756 Also, be sure to put the template under the directory specified in
757 C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our
758 eyecandy debug screen. ;)
762 To show how to define models, again we'll use an already-existing base
763 class, this time for L<Class::DBI>: L<Catalyst::Model::CDBI>.
765 But first, we need a database.
769 id INTEGER PRIMARY KEY,
774 id INTEGER PRIMARY KEY,
775 foo INTEGER REFERENCES foo,
779 INSERT INTO foo (data) VALUES ('TEST!');
782 % sqlite /tmp/myapp.db < myapp.sql
784 Now we can create a CDBI component for this database.
786 package MyApp::Model::CDBI;
789 use base 'Catalyst::Model::CDBI';
792 dsn => 'dbi:SQLite:/tmp/myapp.db',
798 Catalyst automatically loads table layouts and relationships. Use the
799 stash to pass data to your templates.
804 use Catalyst '-Debug';
807 name => 'My Application',
808 root => '/home/joeuser/myapp/root'
814 my ( $self, $c ) = @_;
815 $c->stash->{template} ||= 'index.tt';
816 $c->forward('MyApp::View::TT');
820 my ( $self, $c, $id ) = @_;
821 $c->stash->{item} = MyApp::Model::CDBI::Foo->retrieve($id);
826 # Then, in a TT template:
827 The id is [% item.data %]
829 Models do not have to be part of your Catalyst application; you
830 can always call an outside module that serves as your Model:
834 my ( $self, $c ) = @_;
835 $c->stash->{template} = 'list.tt';
836 use Some::Outside::CDBI::Module;
837 my @records = Some::Outside::CDBI::Module->retrieve_all;
838 $c->stash->{records} = \@records;
841 But by using a Model that is part of your Catalyst application, you gain
842 several things: you don't have to C<use> each component, Catalyst will
843 find and load it automatically at compile-time; you can C<forward> to
844 the module, which can only be done to Catalyst components; and only
845 Catalyst components can be fetched with
846 C<$c-E<gt>model('SomeModel')>.
848 Happily, since many people have existing Model classes that they
849 would like to use with Catalyst (or, conversely, they want to
850 write Catalyst models that can be used outside of Catalyst, e.g.
851 in a cron job), it's trivial to write a simple component in
852 Catalyst that slurps in an outside Model:
854 package MyApp::Model::Catalog;
855 use base qw/Catalyst::Base Some::Other::CDBI::Module::Catalog/;
858 and that's it! Now C<Some::Other::CDBI::Module::Catalog> is part of your
859 Cat app as C<MyApp::Model::Catalog>.
863 Multiple controllers are a good way to separate logical domains of your
866 package MyApp::Controller::Login;
868 sub sign-in : Local { }
869 sub new-password : Local { }
870 sub sign-out : Local { }
872 package MyApp::Controller::Catalog;
877 package MyApp::Controller::Cart;
880 sub update : Local { }
881 sub order : Local { }
885 Catalyst has a built-in http server for testing! (Later, you can easily
886 use a more powerful server, e.g. Apache/mod_perl, in a production
889 Start your application on the command line...
891 script/myapp_server.pl
893 ...then visit http://localhost:3000/ in a browser to view the output.
895 You can also do it all from the command line:
897 script/myapp_test.pl http://localhost/
905 Join #catalyst on irc.perl.org.
909 http://lists.rawmode.org/mailman/listinfo/catalyst
910 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
914 Sebastian Riedel, C<sri@oook.de>
915 David Naughton, C<naughton@umn.edu>
916 Marcus Ramberg, C<mramberg@cpan.org>
917 Jesse Sheidlower, C<jester@panix.com>
918 Danijel Milicevic, C<me@danijel.de>
922 This program is free software, you can redistribute it and/or modify it
923 under the same terms as Perl itself.