3 Catalyst::Manual::Intro - Introduction to Catalyst
7 This is a brief overview of why and how to use Catalyst. It explains how
8 Catalyst works and shows how to get a simple application up and running
11 =head2 What is Catalyst?
13 Catalyst is an elegant web application framework, extremely flexible yet
14 extremely simple. It's similar to Ruby on Rails, Spring (Java) and
15 L<Maypole>, upon which it was originally based.
19 Catalyst follows the Model-View-Controller (MVC) design pattern,
20 allowing you to easily separate concerns, like content, presentation,
21 and flow control, into separate modules. This separation allows you to
22 modify code that handles one concern without affecting code that handles
23 the others. Catalyst promotes the re-use of existing Perl modules that
24 already handle common web application concerns well.
26 Here's how the M, V, and C map to those concerns, with examples of
27 well-known Perl modules you may want to use for each.
33 Access and modify content (data). L<Class::DBI>, L<Plucene>, L<Net::LDAP>...
37 Present content to the user. L<Template Toolkit|Template>,
38 L<Mason|HTML::Mason>, L<HTML::Template>...
42 Control the whole request phase, check parameters, dispatch actions, flow
47 If you're unfamiliar with MVC and design patterns, you may want to check
48 out the original book on the subject, I<Design Patterns>, by Gamma,
49 Helm, Johnson, and Vlissides, also known as the Gang of Four (GoF). You
50 can also just Google it. Many, many web application frameworks are
51 based on MVC, including all those listed above.
55 Catalyst is much more flexible than many other frameworks. We'll talk
56 more about this later, but rest assured you can use your favorite Perl
57 modules with Catalyst.
61 =item * B<Multiple Models, Views, and Controllers>
63 To build a Catalyst application, you handle each type of concern inside
64 special modules called L</Components>. Often this code will be very
65 simple, just calling out to Perl modules like those listed above under
66 L</MVC>. Catalyst handles these components in a very flexible way. Use
67 as many Models, Views, and Controllers as you like, using as many
68 different Perl modules as you like, all in the same application. Want to
69 manipulate multiple databases, and retrieve some data via LDAP? No
70 problem. Want to present data from the same Model using L<Template
71 Toolkit|Template> and L<PDF::Template>? Easy.
73 =item * B<Reuseable Components>
75 Not only does Catalyst promote the re-use of already existing Perl
76 modules, it also allows you to re-use your Catalyst components in
77 multiple Catalyst applications.
79 =item * B<Unrestrained URL-to-Action Dispatching>
81 Catalyst allows you to dispatch any URLs to any application L<Actions>,
82 even through regular expressions! Unlike most other frameworks, it
83 doesn't require mod_rewrite or class and method names in URLs.
85 With Catalyst you register your actions and address them directly. For
89 my ( $self, $context ) = @_;
90 $context->response->body('Hello World!');
93 Now http://localhost:3000/hello prints "Hello World!".
95 =item * B<Support for CGI, mod_perl, Apache::Request>
97 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>.
103 The best part is that Catalyst implements all this flexibility in a very
108 =item * B<Building Block Interface>
110 Components interoperate very smoothly. For example, Catalyst
111 automatically makes a L<Context> object available to every
112 component. Via the context, you can access the request object, share
113 data between components, and control the flow of your
114 application. Building a Catalyst application feels a lot like snapping
115 together toy building blocks, and everything just works.
117 =item * B<Component Auto-Discovery>
119 No need to C<use> all of your components. Catalyst automatically finds
122 =item * B<Pre-Built Components for Popular Modules>
124 See L<Catalyst::Model::CDBI> for L<Class::DBI>, or L<Catalyst::View::TT>
125 for L<Template Toolkit|Template>.
127 =item * B<Built-in Test Framework>
129 Catalyst comes with a built-in, lightweight http server and test
130 framework, making it easy to test applications from the command line.
132 =item * B<Helper Scripts>
134 Catalyst provides helper scripts to quickly generate running starter
135 code for components and unit tests. See L<Catalyst::Helper>.
141 Here's how to install Catalyst and get a simple application up and
142 running, using the helper scripts described above.
146 $ perl -MCPAN -e 'install Task::Catalyst'
153 $ script/myapp_create.pl controller Library::Login
157 $ script/myapp_server.pl
159 Now visit these locations with your favorite browser or user agent to see
164 =item http://localhost:3000/
166 =item http://localhost:3000/library/login/
174 Let's see how Catalyst works, by taking a closer look at the components
175 and other parts of a Catalyst application.
177 =head3 Application Class
179 In addition to the Model, View, and Controller components, there's a
180 single class that represents your application itself. This is where you
181 configure your application, load plugins, define application-wide
182 actions, and extend Catalyst.
187 use Catalyst qw/-Debug/;
190 name => 'My Application',
192 # You can put anything else you want in here:
193 my_configuration_variable => 'something',
196 sub default : Private {
197 my ( $self, $context ) = @_;
198 $context->response->body('Catalyst rocks!');
203 For most applications, Catalyst requires you to define only one config
210 Name of your application.
214 Optionally, you can specify a B<root> parameter for templates and static
215 data. If omitted, Catalyst will try to auto-detect the directory's
216 location. You can define as many parameters as you want for plugins or
217 whatever you need. You can access them anywhere in your application via
218 C<$context-E<gt>config-E<gt>{$param_name}>.
222 Catalyst automatically blesses a Context object into your application
223 class and makes it available everywhere in your application. Use the
224 Context to directly interact with Catalyst and glue your L<Components>
225 together. For example, if you need to use the Context from within a
226 Template Toolkit template, it's already there:
228 <h1>Welcome to [% c.config.name %]!</h1>
230 As illustrated in our URL-to-Action dispatching example, the Context is
231 always the second method parameter, behind the Component object
232 reference or class name itself. Previously we called it C<$context> for
233 clarity, but most Catalyst developers just call it C<$c>:
236 my ( $self, $c ) = @_;
237 $c->res->body('Hello World!');
240 The Context contains several important objects:
244 =item * L<Catalyst::Request>
249 The request object contains all kinds of request-specific information, like
250 query parameters, cookies, uploads, headers, and more.
252 $c->req->params->{foo};
253 $c->req->cookies->{sessionid};
254 $c->req->headers->content_type;
257 =item * L<Catalyst::Response>
262 The response is like the request, but contains just response-specific
265 $c->res->body('Hello World');
266 $c->res->status(404);
267 $c->res->redirect('http://oook.de');
269 =item * L<Catalyst::Config>
275 =item * L<Catalyst::Log>
279 $c->log->debug('Something happened');
280 $c->log->info('Something you should know');
285 $c->stash->{foo} = 'bar';
289 The last of these, the stash, is a universal hash for sharing data among
290 application components. For an example, we return to our 'hello' action:
293 my ( $self, $c ) = @_;
294 $c->stash->{message} = 'Hello World!';
295 $c->forward('show_message');
298 sub show_message : Private {
299 my ( $self, $c ) = @_;
300 $c->res->body( $c->stash->{message} );
303 Note that the stash should be used only for passing data in an
304 individual request cycle; it gets cleared at a new request. If you need
305 to maintain more persistent data, use a session.
309 A Catalyst controller is defined by its actions. An action is a sub with
310 a special attribute. You've already seen some examples of actions in
311 this document. The URL (for example http://localhost.3000/foo/bar)
312 consists of two parts, the base (http://localhost:3000/ in this example)
313 and the path (foo/bar). Please note that the trailing slash after the
314 hostname[:port] always belongs to base and not to the action.
316 Catalyst supports several types of actions:
322 package MyApp::Controller::My::Controller;
323 sub bar : Path('foo/bar') { }
325 Literal C<Path> actions will act relative to their current
326 namespace. The above example matches only
327 http://localhost:3000/my/controller/foo/bar. If you start your path with
328 a forward slash, it will match from the root. Example:
330 package MyApp::Controller::My::Controller;
331 sub bar : Path('/foo/bar') { }
333 Matches only http://localhost:3000/foo/bar.
335 package MyApp::Controller::My::Controller;
338 By leaving the C<Path> definition empty, it will match on the namespace
339 root. The above code matches http://localhost:3000/my/controller.
343 sub bar : Regex('^item(\d+)/order(\d+)$') { }
345 Matches any URL that matches the pattern in the action key, e.g.
346 http://localhost:3000/item23/order42. The '' around the regexp is
347 optional, but perltidy likes it. :)
349 Regex matches act globally, i.e. without reference to the namespace from
350 which it is called, so that a C<bar> method in the
351 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
352 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
353 explicitly put this in the regex. To achieve the above, you should
354 consider using a C<LocalRegex> action.
356 =item * B<LocalRegex>
358 sub bar : LocalRegex('^widget(\d+)$') { }
360 LocalRegex actions act locally. If you were to use C<bar> in
361 C<MyApp::Controller::Catalog>, the above example would match urls like
362 http://localhost:3000/catalog/widget23.
364 If you omit the "C<^>" from your regex, then it will match any depth
365 from the controller and not immediately off of the controller name. The
366 following example differs from the above code in that it will match
367 http://localhost:3000/catalog/foo/widget23 as well.
369 package MyApp::Controller::Catalog;
370 sub bar : LocalRegex('widget(\d+)$') { }
372 For both LocalRegex and Regex actions, if you use capturing parentheses
373 to extract values within the matching URL, those values are available in
374 the C<$c-E<gt>req-E<gt>snippets> array. In the above example, "widget23"
375 would capture "23" in the above example, and
376 C<$c-E<gt>req-E<gt>snippets-E<gt>[0]> would be "23". If you want to pass
377 arguments at the end of your URL, you must use regex action keys. See
378 L</URL Path Handling> below.
385 Matches http://localhost:3000/foo. The function name is mapped directly
386 to the application base.
388 =item * B<Namespace-Prefixed>
390 package MyApp::Controller::My::Controller;
393 Matches http://localhost:3000/my/controller/foo.
395 This action type indicates that the matching URL must be prefixed with a
396 modified form of the component's class (package) name. This modified
397 class name excludes the parts that have a pre-defined meaning in
398 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
399 "/", and converts the name to lower case. See L</Components> for a full
400 explanation of the pre-defined meaning of Catalyst component class
405 sub foo : Private { }
407 Matches no URL, and cannot be executed by requesting a URL that
408 corresponds to the action key. Private actions can be executed only
409 inside a Catalyst application, by calling the C<forward> method:
413 See L</Flow Control> for a full explanation of C<forward>. Note that, as
414 discussed there, when forwarding from another component, you must use
415 the absolute path to the method, so that a private C<bar> method in your
416 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
417 from elsewhere, be reached with
418 C<$c-E<gt>forward('/catalog/order/process/bar')>.
422 B<Note:> After seeing these examples, you probably wonder what the point
423 is of defining names for regex and path actions. Actually, every public
424 action is also a private one, so you have one unified way of addressing
425 components in your C<forward>s.
427 =head4 Built-in Private Actions
429 In response to specific application states, Catalyst will automatically
430 call these built-in private actions in your application class:
434 =item * B<default : Private>
436 Called when no other action matches. Could be used, for example, for
437 displaying a generic frontpage for the main app, or an error page for
438 individual controllers.
440 If C<default> isn't acting how you would expect, look at using a
441 L<Literal> C<Path> action (with an empty path string). The difference is
442 that C<Path> takes arguments relative from the namespace and C<default>
443 I<always> takes arguments relative from the root, regardless of what
446 =item * B<index : Private>
448 C<index> is much like C<default> except that it takes no arguments
449 and it is weighted slightly higher in the matching process. It is
450 useful as a static entry point to a controller, e.g. to have a static
451 welcome page. Note that it's also weighted higher than Path.
453 =item * B<begin : Private>
455 Called at the beginning of a request, before any matching actions are
458 =item * B<end : Private>
460 Called at the end of a request, after all matching actions are called.
464 =head4 Built-in actions in controllers/autochaining
466 Package MyApp::Controller::Foo;
467 sub begin : Private { }
468 sub default : Private { }
469 sub auto : Private { }
471 You can define built-in private actions within your controllers as
472 well. The actions will override the ones in less-specific controllers,
473 or your application class. In other words, for each of the three
474 built-in private actions, only one will be run in any request
475 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
476 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
477 and C<MyApp::Controller::Catalog::Order::begin> would override this in
480 In addition to the normal built-in actions, you have a special action
481 for making chains, C<auto>. Such C<auto> actions will be run after any
482 C<begin>, but before your action is processed. Unlike the other
483 built-ins, C<auto> actions I<do not> override each other; they will be
484 called in turn, starting with the application class and going through to
485 the I<most> specific class. I<This is the reverse of the order in which
486 the normal built-ins override each other>.
488 Here are some examples of the order in which the various built-ins
493 =item for a request for C</foo/foo>
497 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
500 =item for a request for C</foo/bar/foo>
502 MyApp::Controller::Foo::Bar::begin
504 MyApp::Controller::Foo::auto
505 MyApp::Controller::Foo::Bar::auto
506 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
507 MyApp::Controller::Foo::Bar::end
511 The C<auto> action is also distinguished by the fact that you can break
512 out of the processing chain by returning 0. If an C<auto> action returns
513 0, any remaining actions will be skipped, except for C<end>. So, for the
514 request above, if the first auto returns false, the chain would look
519 =item for a request for C</foo/bar/foo> where first C<auto> returns
522 MyApp::Controller::Foo::Bar::begin
524 MyApp::Controller::Foo::Bar::end
528 An example of why one might use this is an authentication action: you
529 could set up a C<auto> action to handle authentication in your
530 application class (which will always be called first), and if
531 authentication fails, returning 0 would skip any remaining methods
534 B<Note:> Looking at it another way, C<auto> actions have to return a
535 true value to continue processing! You can also C<die> in the autochain
536 action; in that case, the request will go straight to the finalize
537 stage, without processing further actions.
539 =head4 URL Path Handling
541 You can pass variable arguments as part of the URL path, separated with
542 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
543 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
544 where C<$bar> and C<$baz> may vary:
546 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
548 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
550 sub boo : Path('foo/boo') { .. }
551 sub hoo : Path('foo/boo/hoo') { .. }
553 Catalyst matches actions in most specific to least specific order:
557 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
559 So Catalyst would never mistakenly dispatch the first two URLs to the
562 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
563 still match a URL containing arguments, however the arguments won't be
566 =head4 Parameter Processing
568 Parameters passed in the URL query string are handled with methods in
569 the L<Catalyst::Request> class. The C<param> method is functionally
570 equivalent to the C<param> method of C<CGI.pm> and can be used in
571 modules that require this.
573 # http://localhost:3000/catalog/view/?category=hardware&page=3
574 my $category = $c->req->param('category');
575 my $current_page = $c->req->param('page') || 1;
577 # multiple values for single parameter name
578 my @values = $c->req->param('scrolling_list');
580 # DFV requires a CGI.pm-like input hash
581 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
585 You control the application flow with the C<forward> method, which
586 accepts the key of an action to execute. This can be an action in the
587 same or another Catalyst controller, or a Class name, optionally
588 followed by a method name. After a C<forward>, the control flow will
589 return to the method from which the C<forward> was issued.
591 A C<forward> is similar to a method call. The main differences are that
592 it wraps the call in an C<eval> to allow exception handling; it
593 automatically passes along the context object (C<$c> or C<$context>);
594 and it allows profiling of each call (displayed in the log with
598 my ( $self, $c ) = @_;
599 $c->stash->{message} = 'Hello World!';
600 $c->forward('check_message'); # $c is automatically included
603 sub check_message : Private {
604 my ( $self, $c ) = @_;
605 return unless $c->stash->{message};
606 $c->forward('show_message');
609 sub show_message : Private {
610 my ( $self, $c ) = @_;
611 $c->res->body( $c->stash->{message} );
614 A C<forward> does not create a new request, so your request
615 object (C<$c-E<gt>req>) will remain unchanged. This is a
616 key difference between using C<forward> and issuing a
619 You can pass new arguments to a C<forward> by adding them
620 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
621 will be changed for the duration of the C<forward> only; upon
622 return, the original value of C<$c-E<gt>req-E<gt>args> will
626 my ( $self, $c ) = @_;
627 $c->stash->{message} = 'Hello World!';
628 $c->forward('check_message',[qw/test1/]);
629 # now $c->req->args is back to what it was before
632 sub check_message : Private {
633 my ( $self, $c ) = @_;
634 my $first_argument = $c->req->args[0]; # now = 'test1'
638 As you can see from these examples, you can just use the method name as
639 long as you are referring to methods in the same controller. If you want
640 to forward to a method in another controller, or the main application,
641 you will have to refer to the method by absolute path.
643 $c->forward('/my/controller/action');
644 $c->forward('/default'); # calls default in main application
646 Here are some examples of how to forward to classes and methods.
649 my ( $self, $c ) = @_;
650 $c->forward(qw/MyApp::Model::Hello say_hello/);
654 my ( $self, $c ) = @_;
655 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
658 package MyApp::Model::Hello;
661 my ( $self, $c ) = @_;
662 $c->res->body('Hello World!');
666 my ( $self, $c ) = @_;
667 $c->res->body('Goodbye World!');
670 Note that C<forward> returns to the calling action and continues
671 processing after the action finishes. If you want all further processing
672 in the calling action to stop, use C<detach> instead, which will execute
673 the C<detach>ed action and not return to the calling sub. In both cases,
674 Catalyst will automatically try to call process() if you omit the
679 Catalyst has an uncommonly flexible component system. You can define as many
680 L<Models>, L<Views>, and L<Controllers> as you like.
682 All components must inherit from L<Catalyst::Base>, which provides a simple
683 class structure and some common class methods like C<config> and C<new>
686 package MyApp::Controller::Catalog;
689 use base 'Catalyst::Base';
691 __PACKAGE__->config( foo => 'bar' );
695 You don't have to C<use> or otherwise register Models, Views, and
696 Controllers. Catalyst automatically discovers and instantiates them
697 when you call C<setup> in the main application. All you need to do is
698 put them in directories named for each Component type. Notice that you
699 can use some very terse aliases for each one.
703 =item * B<MyApp/Model/>
707 =item * B<MyApp/View/>
711 =item * B<MyApp/Controller/>
719 To show how to define views, we'll use an already-existing base class for the
720 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
721 inherit from this class:
723 package MyApp::View::TT;
726 use base 'Catalyst::View::TT';
730 (You can also generate this automatically by using the helper script:
732 script/myapp_create.pl view TT TT
734 where the first C<TT> tells the script that the name of the view should
735 be C<TT>, and the second that it should be a Template Toolkit view.)
737 This gives us a process() method and we can now just do
738 $c->forward('MyApp::View::TT') to render our templates. The base class
739 makes process() implicit, so we don't have to say
740 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
743 my ( $self, $c ) = @_;
744 $c->stash->{template} = 'hello.tt';
748 my ( $self, $c ) = @_;
749 $c->forward('MyApp::View::TT');
752 You normally render templates at the end of a request, so it's a perfect
753 use for the global C<end> action.
755 Also, be sure to put the template under the directory specified in
756 C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our
757 eyecandy debug screen. ;)
761 To show how to define models, again we'll use an already-existing base
762 class, this time for L<Class::DBI>: L<Catalyst::Model::CDBI>.
764 But first, we need a database.
768 id INTEGER PRIMARY KEY,
773 id INTEGER PRIMARY KEY,
774 foo INTEGER REFERENCES foo,
778 INSERT INTO foo (data) VALUES ('TEST!');
781 % sqlite /tmp/myapp.db < myapp.sql
783 Now we can create a CDBI component for this database.
785 package MyApp::Model::CDBI;
788 use base 'Catalyst::Model::CDBI';
791 dsn => 'dbi:SQLite:/tmp/myapp.db',
797 Catalyst automatically loads table layouts and relationships. Use the
798 stash to pass data to your templates.
803 use Catalyst '-Debug';
806 name => 'My Application',
807 root => '/home/joeuser/myapp/root'
813 my ( $self, $c ) = @_;
814 $c->stash->{template} ||= 'index.tt';
815 $c->forward('MyApp::View::TT');
819 my ( $self, $c, $id ) = @_;
820 $c->stash->{item} = MyApp::Model::CDBI::Foo->retrieve($id);
825 # Then, in a TT template:
826 The id is [% item.data %]
828 Models do not have to be part of your Catalyst application; you
829 can always call an outside module that serves as your Model:
833 my ( $self, $c ) = @_;
834 $c->stash->{template} = 'list.tt';
835 use Some::Outside::CDBI::Module;
836 my @records = Some::Outside::CDBI::Module->retrieve_all;
837 $c->stash->{records} = \@records;
840 But by using a Model that is part of your Catalyst application, you gain
841 several things: you don't have to C<use> each component, Catalyst will
842 find and load it automatically at compile-time; you can C<forward> to
843 the module, which can only be done to Catalyst components; and only
844 Catalyst components can be fetched with
845 C<$c-E<gt>model('SomeModel')>.
847 Happily, since many people have existing Model classes that they
848 would like to use with Catalyst (or, conversely, they want to
849 write Catalyst models that can be used outside of Catalyst, e.g.
850 in a cron job), it's trivial to write a simple component in
851 Catalyst that slurps in an outside Model:
853 package MyApp::Model::Catalog;
854 use base qw/Catalyst::Base Some::Other::CDBI::Module::Catalog/;
857 and that's it! Now C<Some::Other::CDBI::Module::Catalog> is part of your
858 Cat app as C<MyApp::Model::Catalog>.
862 Multiple controllers are a good way to separate logical domains of your
865 package MyApp::Controller::Login;
867 sub sign-in : Local { }
868 sub new-password : Local { }
869 sub sign-out : Local { }
871 package MyApp::Controller::Catalog;
876 package MyApp::Controller::Cart;
879 sub update : Local { }
880 sub order : Local { }
884 Catalyst has a built-in http server for testing! (Later, you can easily
885 use a more powerful server, e.g. Apache/mod_perl, in a production
888 Start your application on the command line...
890 script/myapp_server.pl
892 ...then visit http://localhost:3000/ in a browser to view the output.
894 You can also do it all from the command line:
896 script/myapp_test.pl http://localhost/
904 Join #catalyst on irc.perl.org.
908 http://lists.rawmode.org/mailman/listinfo/catalyst
909 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
913 Sebastian Riedel, C<sri@oook.de>
914 David Naughton, C<naughton@umn.edu>
915 Marcus Ramberg, C<mramberg@cpan.org>
916 Jesse Sheidlower, C<jester@panix.com>
917 Danijel Milicevic, C<me@danijel.de>
921 This program is free software, you can redistribute it and/or modify it under
922 the same terms as Perl itself.