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 quickly.
10 =head2 What is Catalyst?
12 Catalyst is an elegant web application framework, extremely flexible yet
13 extremely simple. It's similar to Ruby on Rails, Spring (Java) and L<Maypole>,
14 upon which it was originally based.
18 Catalyst follows the Model-View-Controller (MVC) design pattern, allowing you to
19 easily separate concerns, like content, presentation, and flow control, into
20 separate modules. This separation allows you to modify code that handles one
21 concern without affecting code that handles the others. Catalyst promotes the
22 re-use of existing Perl modules that already handle common web application
25 Here's how the M, V, and C map to those concerns, with examples of well-known
26 Perl modules you may want to use for each.
32 Access and modify content (data). L<Class::DBI>, L<Plucene>, L<Net::LDAP>...
36 Present content to the user. L<Template Toolkit|Template>, L<Mason|HTML::Mason>,
41 Control the whole request phase, check parameters, dispatch actions, flow
46 If you're unfamiliar with MVC and design patterns, you may want to check
47 out the original book on the subject, I<Design Patterns>, by Gamma,
48 Helm, Johnson, and Vlissides, also known as the Gang of Four (GoF). You
49 can also just Google it. Many, many web application frameworks are
50 based on MVC, including all those listed above.
54 Catalyst is much more flexible than many other frameworks. We'll talk more about
55 this later, but rest assured you can use your favorite Perl modules with
60 =item * B<Multiple Models, Views, and Controllers>
62 To build a Catalyst application, you handle each type of concern inside special
63 modules called L</Components>. Often this code will be very simple, just calling
64 out to Perl modules like those listed above under L</MVC>. Catalyst handles
65 these components in a very flexible way. Use as many Models, Views, and
66 Controllers as you like, using as many different Perl modules as you like, all
67 in the same application. Want to manipulate multiple databases, and retrieve
68 some data via LDAP? No problem. Want to present data from the same Model using
69 L<Template Toolkit|Template> and L<PDF::Template>? Easy.
71 =item * B<Reuseable Components>
73 Not only does Catalyst promote the re-use of already existing Perl modules, it
74 also allows you to re-use your Catalyst components in multiple Catalyst
77 =item * B<Unrestrained URL-to-Action Dispatching>
79 Catalyst allows you to dispatch any URLs to any application L<Actions>, even
80 through regular expressions! Unlike most other frameworks, it doesn't require
81 mod_rewrite or class and method names in URLs.
83 With Catalyst you register your actions and address them directly. For example:
86 my ( $self, $context ) = @_;
87 $context->response->body('Hello World!');
90 Now http://localhost:3000/hello prints "Hello World!".
92 =item * B<Support for CGI, mod_perl, Apache::Request>
94 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>.
100 The best part is that Catalyst implements all this flexibility in a very simple
105 =item * B<Building Block Interface>
107 Components interoperate very smoothly. For example, Catalyst automatically makes
108 a L<Context> object available to every component. Via the context, you can
109 access the request object, share data between components, and control the flow
110 of your application. Building a Catalyst application feels a lot like snapping
111 together toy building blocks, and everything just works.
113 =item * B<Component Auto-Discovery>
115 No need to C<use> all of your components. Catalyst automatically finds and loads
118 =item * B<Pre-Built Components for Popular Modules>
120 See L<Catalyst::Model::CDBI> for L<Class::DBI>, or L<Catalyst::View::TT> for
121 L<Template Toolkit|Template>. You can even get an instant web database front end
122 with L<Catalyst::Model::CDBI::CRUD>.
124 =item * B<Built-in Test Framework>
126 Catalyst comes with a built-in, lightweight http server and test framework,
127 making it easy to test applications from the command line.
129 =item * B<Helper Scripts>
131 Catalyst provides helper scripts to quickly generate running starter code for
132 components and unit tests.
138 Here's how to install Catalyst and get a simple application up and running,
139 using the helper scripts described above.
143 $ perl -MCPAN -e 'install Bundle::Catalyst'
150 $ script/myapp_create.pl controller Library::Login
154 $ script/myapp_server.pl
156 Now visit these locations with your favorite browser or user agent to see
161 =item http://localhost:3000/
163 =item http://localhost:3000/library/login/
171 Let's see how Catalyst works, by taking a closer look at the components and
172 other parts of a Catalyst application.
174 =head3 Application Class
176 In addition to the Model, View, and Controller components, there's a single
177 class that represents your application itself. This is where you configure your
178 application, load plugins, define application-wide actions, and extend Catalyst.
183 use Catalyst qw/-Debug/;
186 name => 'My Application',
188 # You can put anything else you want in here:
189 my_configuration_variable => 'something',
192 sub default : Private {
193 my ( $self, $context ) = @_;
194 $context->response->body('Catalyst rockz!');
199 For most applications, Catalyst requires you to define only one config
206 Name of your application.
210 Optionally, you can specify a B<root> parameter for templates and static data.
211 If omitted, Catalyst will try to auto-detect the directory's location. You
212 can define as many parameters as you want for plugins or whatever you
213 need. You can access them anywhere in your application
214 via C<$context-E<gt>config-E<gt>{$param_name}>.
218 Catalyst automatically blesses a Context object into your application class and
219 makes it available everywhere in your application. Use the Context to directly
220 interact with Catalyst and glue your L<Components> together. For example, if you
221 need to use the Context from within a Template Toolkit template, it's already
224 <h1>Welcome to [% c.config.name %]!</h1>
226 As illustrated earlier in our URL-to-Action dispatching example, the Context is
227 always the second method parameter, behind the Component object reference or
228 class name itself. Previously we called it C<$context> for clarity, but most
229 Catalyst developers just call it C<$c>:
232 my ( $self, $c ) = @_;
233 $c->res->body('Hello World!');
236 The Context contains several important objects:
240 =item * L<Catalyst::Request>
245 The request object contains all kinds of request-specific information, like
246 query parameters, cookies, uploads, headers, and more.
248 $c->req->params->{foo};
249 $c->req->cookies->{sessionid};
250 $c->req->headers->content_type;
253 =item * L<Catalyst::Response>
258 The response is like the request, but contains just response-specific
261 $c->res->body('Hello World');
262 $c->res->status(404);
263 $c->res->redirect('http://oook.de');
265 =item * L<Catalyst::Config>
272 =item * L<Catalyst::Log>
276 $c->log->debug('Something happened');
277 $c->log->info('Something you should know');
283 $c->stash->{foo} = 'bar';
287 The last of these, the stash, is a universal hash for sharing data among
288 application components. For an example, we return to our 'hello' action:
291 my ( $self, $c ) = @_;
292 $c->stash->{message} = 'Hello World!';
293 $c->forward('show_message');
296 sub show_message : Private {
297 my ( $self, $c ) = @_;
298 $c->res->body( $c->stash->{message} );
301 Note that the stash should be used only for passing data in an individual
302 request cycle; it gets cleared at a new request. If you need to maintain more
303 persistent data, use a session.
307 A Catalyst controller is defined by its actions. An action is a sub with a
308 special attribute. You've already seen some examples of actions in this
309 document. The URL (for example http://localhost.3000/foo/bar) consists of two
310 parts, the base (http://localhost:3000/ in this example) and the path (foo/bar).
311 Please note that the trailing slash after the hostname[:port] always belongs to
312 base and not to the action.
314 Catalyst supports several types of actions:
320 package MyApp::C::My::Controller;
321 sub bar : Path('foo/bar') { }
323 Literal C<Path> actions will act relative to their current namespace. The above
324 example matches only http://localhost:3000/my/controller/foo/bar. If you start
325 your path with a forward slash, it will match from the root. Example:
327 package MyApp::C::My::Controller;
328 sub bar : Path('/foo/bar') { }
330 Matches only http://localhost:3000/foo/bar.
332 package MyApp::C::My::Controller;
335 By leaving the C<Path> definition empty, it will match on the namespace root.
336 The above code matches http://localhost:3000/my/controller.
340 sub bar : Regex('^item(\d+)/order(\d+)$') { }
342 Matches any URL that matches the pattern in the action key, e.g.
343 http://localhost:3000/item23/order42. The '' around the regexp is optional, but
344 perltidy likes it. :)
346 Regex matches act globally, i.e. without reference to the namespace from which
347 it is called, so that a C<bar> method in the
348 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any form of
349 C<bar>, C<Catalog>, C<Order>, or C<Process> unless you explicitly put this in
350 the regex. To achieve the above, you should consider using a C<LocalRegex> action.
352 =item * B<LocalRegex>
354 sub bar : LocalRegex('^widget(\d+)$') { }
356 LocalRegex actions act locally. If you were to use C<bar> in
357 C<MyApp::Controller::Catalog>, the above example would match urls like
358 http://localhost:3000/catalog/widget23.
360 If you omit the "C<^>" from your regex, then it will match any depth from the
361 controller and not immediately off of the controller name. The following example
362 differes from the above code in that it will match
363 http://localhost:3000/catalog/foo/widget23 as well.
365 package MyApp::Controller::Catalog;
366 sub bar : LocalRegex('widget(\d+)$') { }
368 For both LocalRegex and Regex actions, if you use capturing parentheses to
369 extract values within the matching URL ("widget23" would capture "23" in the
370 above example), those values are available in the $c->req->snippets
371 array. If you want to pass arguments at the end of your URL, you must use regex
372 action keys. See L</URL Path Handling> below.
379 Matches http://localhost:3000/foo. The function name is mapped directly
380 to the application base.
382 =item * B<Namespace-Prefixed>
384 package MyApp::C::My::Controller;
387 Matches http://localhost:3000/my/controller/foo.
389 This action type indicates that the matching URL must be prefixed with a
390 modified form of the component's class (package) name. This modified class name
391 excludes the parts that have a pre-defined meaning in Catalyst ("MyApp::C" in
392 the above example), replaces "::" with "/", and converts the name to lower case.
393 See L</Components> for a full explanation of the pre-defined meaning of Catalyst
394 component class names.
398 sub foo : Private { }
400 Matches no URL, and cannot be executed by requesting a URL that corresponds to
401 the action key. Private actions can be executed only inside a Catalyst
402 application, by calling the C<forward> method:
406 See L</Flow Control> for a full explanation of C<forward>. Note that, as
407 discussed there, when forwarding from another component, you must use
408 the absolute path to the method, so that a private C<bar> method in your
409 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
410 from elsewhere, be reached with
411 C<$c-E<gt>forward('/catalog/order/process/bar')>.
415 B<Note:> After seeing these examples, you probably wonder what the point
416 is of defining names for regex and path actions. Actually, every public
417 action is also a private one, so you have one unified way of addressing
418 components in your C<forward>s.
420 =head4 Built-in Private Actions
422 In response to specific application states, Catalyst will automatically
423 call these built-in private actions in your application class:
427 =item * B<default : Private>
429 Called when no other action matches. Could be used, for example, for
430 displaying a generic frontpage for the main app, or an error page for
431 individual controllers.
433 If C<default> isn't acting how you would expect, look at using a
434 L<Literal> C<Path> action (with an empty path string). The difference
435 being that C<Path> takes arguments relative from the namespace and
436 C<default> takes arguments relative from the root.
438 =item * B<index : Private>
440 C<index> is much like C<default> except that it takes no arguments
441 and it is weighted slightly higher in the matching process.
443 =item * B<begin : Private>
445 Called at the beginning of a request, before any matching actions are
448 =item * B<end : Private>
450 Called at the end of a request, after all matching actions are called.
454 =head4 Built-in actions in controllers/autochaining
456 Package MyApp::C::Foo;
457 sub begin : Private { }
458 sub default : Private { }
459 sub auto : Private { }
461 You can define built-in private actions within your controllers as
462 well. The actions will override the ones in less-specific controllers,
463 or your application class. In other words, for each of the three
464 built-in private actions, only one will be run in any request
465 cycle. Thus, if C<MyApp::C::Catalog::begin> exists, it will be run in
466 place of C<MyApp::begin> if you're in the C<catalog> namespace, and
467 C<MyApp::C::Catalog::Order::begin> would override this in turn.
469 In addition to the normal built-in actions, you have a special action
470 for making chains, C<auto>. Such C<auto> actions will be run after any
471 C<begin>, but before your action is processed. Unlike the other
472 built-ins, C<auto> actions I<do not> override each other; they will be
473 called in turn, starting with the application class and going through to
474 the I<most> specific class. I<This is the reverse of the order in which
475 the normal built-ins override each other>.
477 Here are some examples of the order in which the various built-ins
482 =item for a request for C</foo/foo>
486 MyApp::C::Foo::default # in the absence of MyApp::C::Foo::Foo
489 =item for a request for C</foo/bar/foo>
491 MyApp::C::Foo::Bar::begin
494 MyApp::C::Foo::Bar::auto
495 MyApp::C::Foo::Bar::default # for MyApp::C::Foo::Bar::foo
496 MyApp::C::Foo::Bar::end
500 The C<auto> action is also distinguished by the fact that you can break
501 out of the processing chain by returning 0. If an C<auto> action returns
502 0, any remaining actions will be skipped, except for C<end>. So, for the
503 request above, if the first auto returns false, the chain would look
508 =item for a request for C</foo/bar/foo> where first C<auto> returns
511 MyApp::C::Foo::Bar::begin
513 MyApp::C::Foo::Bar::end
517 An example of why one might use this is an authentication action: you
518 could set up a C<auto> action to handle authentication in your
519 application class (which will always be called first), and if
520 authentication fails, returning 0 would skip any remaining methods
523 B<Note:> Looking at it another way, C<auto> actions have to return a
524 true value to continue processing! You can also C<die> in the autochain
525 action; in that case, the request will go straight to the finalize
526 stage, without processing further actions.
528 =head4 URL Path Handling
530 You can pass variable arguments as part of the URL path. In this case,
531 you must use regex action keys with '^' and '$' anchors, and the
532 arguments must be separated with forward slashes (/) in the URL. For
533 example, suppose you want to handle C</foo/$bar/$baz>, where C<$bar> and
536 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
538 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
540 sub boo : Path('foo/boo') { .. }
541 sub hoo : Path('foo/boo/hoo') { .. }
543 Catalyst matches actions in most specific to least specific order:
547 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
549 So Catalyst would never mistakenly dispatch the first two URLs to the
552 =head4 Parameter Processing
554 Parameters passed in the URL query string are handled with methods in
555 the L<Catalyst::Request> class. The C<param> method is functionally
556 equivalent to the C<param> method of C<CGI.pm> and can be used in
557 modules that require this.
559 # http://localhost:3000/catalog/view/?category=hardware&page=3
560 my $category = $c->req->param('category');
561 my $current_page = $c->req->param('page') || 1;
563 # multiple values for single parameter name
564 my @values = $c->req->param('scrolling_list');
566 # DFV requires a CGI.pm-like input hash
567 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
571 You control the application flow with the C<forward> method, which
572 accepts the key of an action to execute. This can be an action in the
573 same or another Catalyst controller, or a Class name, optionally
574 followed by a method name. After a C<forward>, the control flow will
575 return to the method from which the C<forward> was issued.
577 A C<forward> is similar to a method call. The main differences are that
578 it wraps the call in an C<eval> to allow exception handling; it
579 automatically passes along the context object (C<$c> or C<$context>);
580 and it allows profiling of each call (displayed in the log with
584 my ( $self, $c ) = @_;
585 $c->stash->{message} = 'Hello World!';
586 $c->forward('check_message'); # $c is automatically included
589 sub check_message : Private {
590 my ( $self, $c ) = @_;
591 return unless $c->stash->{message};
592 $c->forward('show_message');
595 sub show_message : Private {
596 my ( $self, $c ) = @_;
597 $c->res->body( $c->stash->{message} );
600 A C<forward> does not create a new request, so your request
601 object (C<$c-E<gt>req>) will remain unchanged. This is a
602 key difference between using C<forward> and issuing a
605 You can pass new arguments to a C<forward> by adding them
606 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
607 will be changed for the duration of the C<forward> only; upon
608 return, the original value of C<$c-E<gt>req-E<gt>args> will
612 my ( $self, $c ) = @_;
613 $c->stash->{message} = 'Hello World!';
614 $c->forward('check_message',[qw/test1/]);
615 # now $c->req->args is back to what it was before
618 sub check_message : Private {
619 my ( $self, $c ) = @_;
620 my $first_argument = $c->req->args[0]; # now = 'test1'
624 As you can see from these examples, you can just use the method name as
625 long as you are referring to methods in the same controller. If you want
626 to forward to a method in another controller, or the main application,
627 you will have to refer to the method by absolute path.
629 $c->forward('/my/controller/action');
630 $c->forward('/default'); # calls default in main application
632 Here are some examples of how to forward to classes and methods.
635 my ( $self, $c ) = @_;
636 $c->forward(qw/MyApp::M::Hello say_hello/);
640 my ( $self, $c ) = @_;
641 $c->forward('MyApp::M::Hello'); # no method: will try 'process'
644 package MyApp::M::Hello;
647 my ( $self, $c ) = @_;
648 $c->res->body('Hello World!');
652 my ( $self, $c ) = @_;
653 $c->res->body('Goodbye World!');
656 Note that C<forward> returns to the calling action and continues
657 processing after the action finishes. If you want all further processing
658 in the calling action to stop, use C<detach> instead, which will execute
659 the C<detach>ed action and not return to the calling sub. In both cases,
660 Catalyst will automatically try to call process() if you omit the
665 Catalyst has an uncommonly flexible component system. You can define as many
666 L<Models>, L<Views>, and L<Controllers> as you like.
668 All components must inherit from L<Catalyst::Base>, which provides a simple
669 class structure and some common class methods like C<config> and C<new>
672 package MyApp::C::Catalog;
675 use base 'Catalyst::Base';
677 __PACKAGE__->config( foo => 'bar' );
681 You don't have to C<use> or otherwise register Models, Views, and
682 Controllers. Catalyst automatically discovers and instantiates them
683 when you call C<setup> in the main application. All you need to do is
684 put them in directories named for each Component type. Notice that you
685 can use some very terse aliases for each one.
689 =item * B<MyApp/Model/>
693 =item * B<MyApp/View/>
697 =item * B<MyApp/Controller/>
705 To show how to define views, we'll use an already-existing base class for the
706 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
707 inherit from this class:
709 package MyApp::V::TT;
712 use base 'Catalyst::View::TT';
716 (You can also generate this automatically by using the helper script:
718 script/myapp_create.pl view TT TT
720 where the first C<TT> tells the script that the name of the view should
721 be C<TT>, and the second that it should be a Template Toolkit view.)
723 This gives us a process() method and we can now just do
724 $c->forward('MyApp::V::TT') to render our templates. The base class makes
725 process() implicit, so we don't have to say C<$c-E<gt>forward(qw/MyApp::V::TT
729 my ( $self, $c ) = @_;
730 $c->stash->{template} = 'hello.tt';
734 my ( $self, $c ) = @_;
735 $c->forward('MyApp::V::TT');
738 You normally render templates at the end of a request, so it's a perfect
739 use for the global C<end> action.
741 Also, be sure to put the template under the directory specified in
742 C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our
743 eyecandy debug screen. ;)
747 To show how to define models, again we'll use an already-existing base class,
748 this time for L<Class::DBI>: L<Catalyst::Model::CDBI>.
750 But first, we need a database.
754 id INTEGER PRIMARY KEY,
759 id INTEGER PRIMARY KEY,
760 foo INTEGER REFERENCES foo,
764 INSERT INTO foo (data) VALUES ('TEST!');
767 % sqlite /tmp/myapp.db < myapp.sql
769 Now we can create a CDBI component for this database.
771 package MyApp::M::CDBI;
774 use base 'Catalyst::Model::CDBI';
777 dsn => 'dbi:SQLite:/tmp/myapp.db',
783 Catalyst automatically loads table layouts and relationships. Use the stash to
784 pass data to your templates.
789 use Catalyst '-Debug';
792 name => 'My Application',
793 root => '/home/joeuser/myapp/root'
799 my ( $self, $c ) = @_;
800 $c->stash->{template} ||= 'index.tt';
801 $c->forward('MyApp::V::TT');
805 my ( $self, $c, $id ) = @_;
806 $c->stash->{item} = MyApp::M::CDBI::Foo->retrieve($id);
811 # Then, in a TT template:
812 The id is [% item.data %]
814 Models do not have to be part of your Catalyst application; you
815 can always call an outside module that serves as your Model:
819 my ( $self, $c ) = @_;
820 $c->stash->{template} = 'list.tt';
821 use Some::Outside::CDBI::Module;
822 my @records = Some::Outside::CDBI::Module->retrieve_all;
823 $c->stash->{records} = \@records;
826 But by using a Model that is part of your Catalyst application, you gain
827 several things: you don't have to C<use> each component, Catalyst will
828 find and load it automatically at compile-time; you can C<forward> to
829 the module, which can only be done to Catalyst components; and only
830 Catalyst components can be fetched with
831 C<$c-E<gt>comp('MyApp::M::SomeModel')>.
833 Happily, since many people have existing Model classes that they
834 would like to use with Catalyst (or, conversely, they want to
835 write Catalyst models that can be used outside of Catalyst, e.g.
836 in a cron job), it's trivial to write a simple component in
837 Catalyst that slurps in an outside Model:
839 package MyApp::M::Catalog;
840 use base qw/Catalyst::Base Some::Other::CDBI::Module::Catalog/;
843 and that's it! Now C<Some::Other::CDBI::Module::Catalog> is part of your
844 Cat app as C<MyApp::M::Catalog>.
848 Multiple controllers are a good way to separate logical domains of your
851 package MyApp::C::Login;
853 sub sign-in : Local { }
854 sub new-password : Local { }
855 sub sign-out : Local { }
857 package MyApp::C::Catalog;
862 package MyApp::C::Cart;
865 sub update : Local { }
866 sub order : Local { }
870 Catalyst has a built-in http server for testing! (Later, you can easily use a
871 more powerful server, e.g. Apache/mod_perl, in a production environment.)
873 Start your application on the command line...
875 script/myapp_server.pl
877 ...then visit http://localhost:3000/ in a browser to view the output.
879 You can also do it all from the command line:
881 script/myapp_test.pl http://localhost/
889 Join #catalyst on irc.perl.org.
893 http://lists.rawmode.org/mailman/listinfo/catalyst
894 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
898 Sebastian Riedel, C<sri@oook.de>
899 David Naughton, C<naughton@umn.edu>
900 Marcus Ramberg, C<mramberg@cpan.org>
901 Jesse Sheidlower, C<jester@panix.com>
902 Danijel Milicevic, C<me@danijel.de>
906 This program is free software, you can redistribute it and/or modify it under
907 the same terms as Perl itself.