3 Catalyst::Manual::Intro - Introduction to Catalyst
7 This is a brief introduction to Catalyst. 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<DBIx::Class>, L<Class::DBI>,
35 L<Plucene>, L<Net::LDAP>...
39 Present content to the user. L<Template Toolkit|Template>,
40 L<Mason|HTML::Mason>, L<HTML::Template>...
44 Control the whole request phase, check parameters, dispatch actions, flow
45 control. Catalyst itself!
49 If you're unfamiliar with MVC and design patterns, you may want to check
50 out the original book on the subject, I<Design Patterns>, by Gamma,
51 Helm, Johnson, and Vlissides, also known as the Gang of Four (GoF).
52 Many, many web application frameworks are based on MVC, including all
57 Catalyst is much more flexible than many other frameworks. We'll talk
58 more about this later, but rest assured you can use your favorite Perl
59 modules with Catalyst.
63 =item * B<Multiple Models, Views, and Controllers>
65 To build a Catalyst application, you handle each type of concern inside
66 special modules called L</Components>. Often this code will be very
67 simple, just calling out to Perl modules like those listed above under
68 L</MVC>. Catalyst handles these components in a very flexible way. Use
69 as many Models, Views, and Controllers as you like, using as many
70 different Perl modules as you like, all in the same application. Want to
71 manipulate multiple databases, and retrieve some data via LDAP? No
72 problem. Want to present data from the same Model using L<Template
73 Toolkit|Template> and L<PDF::Template>? Easy.
75 =item * B<Reuseable Components>
77 Not only does Catalyst promote the re-use of already existing Perl
78 modules, it also allows you to re-use your Catalyst components in
79 multiple Catalyst applications.
81 =item * B<Unrestrained URL-to-Action Dispatching>
83 Catalyst allows you to dispatch any URLs to any application L</Actions>,
84 even through regular expressions! Unlike most other frameworks, it
85 doesn't require mod_rewrite or class and method names in URLs.
87 With Catalyst you register your actions and address them directly. For
91 my ( $self, $context ) = @_;
92 $context->response->body('Hello World!');
95 Now http://localhost:3000/hello prints "Hello World!".
97 =item * B<Support for CGI, mod_perl, Apache::Request>
99 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>.
105 The best part is that Catalyst implements all this flexibility in a very
110 =item * B<Building Block Interface>
112 Components interoperate very smoothly. For example, Catalyst
113 automatically makes a L</Context> object available to every
114 component. Via the context, you can access the request object, share
115 data between components, and control the flow of your
116 application. Building a Catalyst application feels a lot like snapping
117 together toy building blocks, and everything just works.
119 =item * B<Component Auto-Discovery>
121 No need to C<use> all of your components. Catalyst automatically finds
124 =item * B<Pre-Built Components for Popular Modules>
126 See L<Catalyst::Model::DBIC::Schema> for L<DBIx::Class>, or
127 L<Catalyst::View::TT> for L<Template Toolkit|Template>.
129 =item * B<Built-in Test Framework>
131 Catalyst comes with a built-in, lightweight http server and test
132 framework, making it easy to test applications from the command line.
134 =item * B<Helper Scripts>
136 Catalyst provides helper scripts to quickly generate running starter
137 code for components and unit tests. See L<Catalyst::Helper>.
143 Here's how to install Catalyst and get a simple application up and
144 running, using the helper scripts described above.
148 $ perl -MCPAN -e 'install Task::Catalyst'
155 $ script/myapp_create.pl controller Library::Login
159 $ script/myapp_server.pl
161 Now visit these locations with your favorite browser or user agent to see
164 (NOTE: Although we create a controller here, we don't actually use it.
165 Both of these URLs should take you to the welcome page.)
170 =item http://localhost:3000/
172 =item http://localhost:3000/library/login/
180 Let's see how Catalyst works, by taking a closer look at the components
181 and other parts of a Catalyst application.
183 =head3 Application Class
185 In addition to the Model, View, and Controller components, there's a
186 single class that represents your application itself. This is where you
187 configure your application, load plugins, define application-wide
188 actions, and extend Catalyst.
193 use Catalyst qw/-Debug/;
196 name => 'My Application',
198 # You can put anything else you want in here:
199 my_configuration_variable => 'something',
202 sub default : Private {
203 my ( $self, $context ) = @_;
204 $context->response->body('Catalyst rocks!');
209 For most applications, Catalyst requires you to define only one config
216 The name of your application.
220 Optionally, you can specify a B<root> parameter for templates and static
221 data. If omitted, Catalyst will try to auto-detect the directory's
222 location. You can define as many parameters as you want for plugins or
223 whatever you need. You can access them anywhere in your application via
224 C<$context-E<gt>config-E<gt>{$param_name}>.
228 Catalyst automatically blesses a Context object into your application
229 class and makes it available everywhere in your application. Use the
230 Context to directly interact with Catalyst and glue your L</Components>
231 together. For example, if you need to use the Context from within a
232 Template Toolkit template, it's already there:
234 <h1>Welcome to [% c.config.name %]!</h1>
236 As illustrated in our URL-to-Action dispatching example, the Context is
237 always the second method parameter, behind the Component object
238 reference or class name itself. Previously we called it C<$context> for
239 clarity, but most Catalyst developers just call it C<$c>:
242 my ( $self, $c ) = @_;
243 $c->res->body('Hello World!');
246 The Context contains several important objects:
250 =item * L<Catalyst::Request>
255 The request object contains all kinds of request-specific information, like
256 query parameters, cookies, uploads, headers, and more.
258 $c->req->params->{foo};
259 $c->req->cookies->{sessionid};
260 $c->req->headers->content_type;
263 =item * L<Catalyst::Response>
268 The response is like the request, but contains just response-specific
271 $c->res->body('Hello World');
272 $c->res->status(404);
273 $c->res->redirect('http://oook.de');
275 =item * L<Catalyst::Config>
281 =item * L<Catalyst::Log>
284 $c->log->debug('Something happened');
285 $c->log->info('Something you should know');
290 $c->stash->{foo} = 'bar';
294 The last of these, the stash, is a universal hash for sharing data among
295 application components. For an example, we return to our 'hello' action:
298 my ( $self, $c ) = @_;
299 $c->stash->{message} = 'Hello World!';
300 $c->forward('show_message');
303 sub show_message : Private {
304 my ( $self, $c ) = @_;
305 $c->res->body( $c->stash->{message} );
308 Note that the stash should be used only for passing data in an
309 individual request cycle; it gets cleared at a new request. If you need
310 to maintain more persistent data, use a session.
314 A Catalyst controller is defined by its actions. An action is a
315 subroutine with a special attribute. You've already seen some examples
316 of actions in this document. The URL (for example
317 http://localhost.3000/foo/bar) consists of two parts, the base
318 (http://localhost:3000/ in this example) and the path (foo/bar). Please
319 note that the trailing slash after the hostname[:port] always belongs to
320 base and not to the action.
322 Catalyst supports several types of actions:
326 =item * B<Literal> (B<Path> actions)
328 package MyApp::Controller::My::Controller;
329 sub bar : Path('foo/bar') { }
331 Literal C<Path> actions will act relative to their current
332 namespace. The above example matches only
333 http://localhost:3000/my/controller/foo/bar. If you start your path with
334 a forward slash, it will match from the root. Example:
336 package MyApp::Controller::My::Controller;
337 sub bar : Path('/foo/bar') { }
339 Matches only http://localhost:3000/foo/bar.
341 package MyApp::Controller::My::Controller;
344 By leaving the C<Path> definition empty, it will match on the namespace
345 root. The above code matches http://localhost:3000/my/controller.
349 sub bar : Regex('^item(\d+)/order(\d+)$') { }
351 Matches any URL that matches the pattern in the action key, e.g.
352 http://localhost:3000/item23/order42. The '' around the regexp is
353 optional, but perltidy likes it. :)
355 Regex matches act globally, i.e. without reference to the namespace from
356 which it is called, so that a C<bar> method in the
357 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
358 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
359 explicitly put this in the regex. To achieve the above, you should
360 consider using a C<LocalRegex> action.
362 =item * B<LocalRegex>
364 sub bar : LocalRegex('^widget(\d+)$') { }
366 LocalRegex actions act locally. If you were to use C<bar> in
367 C<MyApp::Controller::Catalog>, the above example would match urls like
368 http://localhost:3000/catalog/widget23.
370 If you omit the "C<^>" from your regex, then it will match any depth
371 from the controller and not immediately off of the controller name. The
372 following example differs from the above code in that it will match
373 http://localhost:3000/catalog/foo/widget23 as well.
375 package MyApp::Controller::Catalog;
376 sub bar : LocalRegex('widget(\d+)$') { }
378 For both LocalRegex and Regex actions, if you use capturing parentheses
379 to extract values within the matching URL, those values are available in
380 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
381 would capture "23" in the above example, and
382 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
383 arguments at the end of your URL, you must use regex action keys. See
384 L</URL Path Handling> below.
386 =item * B<Top-level> (B<Global>)
391 Matches http://localhost:3000/foo. The function name is mapped directly
392 to the application base.
394 =item * B<Namespace-Prefixed> (B<Local>)
396 package MyApp::Controller::My::Controller;
399 Matches http://localhost:3000/my/controller/foo.
401 This action type indicates that the matching URL must be prefixed with a
402 modified form of the component's class (package) name. This modified
403 class name excludes the parts that have a pre-defined meaning in
404 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
405 "/", and converts the name to lower case. See L</Components> for a full
406 explanation of the pre-defined meaning of Catalyst component class
411 sub foo : Private { }
413 Matches no URL, and cannot be executed by requesting a URL that
414 corresponds to the action key. Private actions can be executed only
415 inside a Catalyst application, by calling the C<forward> method:
419 See L</Flow Control> for a full explanation of C<forward>. Note that, as
420 discussed there, when forwarding from another component, you must use
421 the absolute path to the method, so that a private C<bar> method in your
422 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
423 from elsewhere, be reached with
424 C<$c-E<gt>forward('/catalog/order/process/bar')>.
428 B<Note:> After seeing these examples, you probably wonder what the point
429 is of defining names for regex and path actions. Every public action is
430 also a private one, so you have one unified way of addressing components
433 =head4 Built-in Private Actions
435 In response to specific application states, Catalyst will automatically
436 call these built-in private actions in your application class:
440 =item * B<default : Private>
442 Called when no other action matches. Could be used, for example, for
443 displaying a generic frontpage for the main app, or an error page for
444 individual controllers.
446 If C<default> isn't acting how you would expect, look at using a
447 L</Literal> C<Path> action (with an empty path string). The difference is
448 that C<Path> takes arguments relative from the namespace and C<default>
449 I<always> takes arguments relative from the root, regardless of what
452 =item * B<index : Private>
454 C<index> is much like C<default> except that it takes no arguments
455 and it is weighted slightly higher in the matching process. It is
456 useful as a static entry point to a controller, e.g. to have a static
457 welcome page. Note that it's also weighted higher than Path.
459 =item * B<begin : Private>
461 Called at the beginning of a request, before any matching actions are
464 =item * B<end : Private>
466 Called at the end of a request, after all matching actions are called.
470 =head4 Built-in actions in controllers/autochaining
472 Package MyApp::Controller::Foo;
473 sub begin : Private { }
474 sub default : Private { }
475 sub auto : Private { }
477 You can define built-in private actions within your controllers as
478 well. The actions will override the ones in less-specific controllers,
479 or your application class. In other words, for each of the three
480 built-in private actions, only one will be run in any request
481 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
482 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
483 and C<MyApp::Controller::Catalog::Order::begin> would override this in
486 In addition to the normal built-in actions, you have a special action
487 for making chains, C<auto>. Such C<auto> actions will be run after any
488 C<begin>, but before your action is processed. Unlike the other
489 built-ins, C<auto> actions I<do not> override each other; they will be
490 called in turn, starting with the application class and going through to
491 the I<most> specific class. I<This is the reverse of the order in which
492 the normal built-ins override each other>.
494 Here are some examples of the order in which the various built-ins
499 =item for a request for C</foo/foo>
503 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
506 =item for a request for C</foo/bar/foo>
508 MyApp::Controller::Foo::Bar::begin
510 MyApp::Controller::Foo::auto
511 MyApp::Controller::Foo::Bar::auto
512 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
513 MyApp::Controller::Foo::Bar::end
517 The C<auto> action is also distinguished by the fact that you can break
518 out of the processing chain by returning 0. If an C<auto> action returns
519 0, any remaining actions will be skipped, except for C<end>. So, for the
520 request above, if the first auto returns false, the chain would look
525 =item for a request for C</foo/bar/foo> where first C<auto> returns
528 MyApp::Controller::Foo::Bar::begin
530 MyApp::Controller::Foo::Bar::end
534 An example of why one might use this is an authentication action: you
535 could set up a C<auto> action to handle authentication in your
536 application class (which will always be called first), and if
537 authentication fails, returning 0 would skip any remaining methods
540 B<Note:> Looking at it another way, C<auto> actions have to return a
541 true value to continue processing! You can also C<die> in the autochain
542 action; in that case, the request will go straight to the finalize
543 stage, without processing further actions.
545 =head4 URL Path Handling
547 You can pass variable arguments as part of the URL path, separated with
548 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
549 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
550 where C<$bar> and C<$baz> may vary:
552 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
554 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
556 sub boo : Path('foo/boo') { .. }
557 sub hoo : Path('foo/boo/hoo') { .. }
559 Catalyst matches actions in most specific to least specific order:
563 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
565 So Catalyst would never mistakenly dispatch the first two URLs to the
568 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
569 still match a URL containing arguments, however the arguments won't be
572 =head4 Parameter Processing
574 Parameters passed in the URL query string are handled with methods in
575 the L<Catalyst::Request> class. The C<param> method is functionally
576 equivalent to the C<param> method of C<CGI.pm> and can be used in
577 modules that require this.
579 # http://localhost:3000/catalog/view/?category=hardware&page=3
580 my $category = $c->req->param('category');
581 my $current_page = $c->req->param('page') || 1;
583 # multiple values for single parameter name
584 my @values = $c->req->param('scrolling_list');
586 # DFV requires a CGI.pm-like input hash
587 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
591 You control the application flow with the C<forward> method, which
592 accepts the key of an action to execute. This can be an action in the
593 same or another Catalyst controller, or a Class name, optionally
594 followed by a method name. After a C<forward>, the control flow will
595 return to the method from which the C<forward> was issued.
597 A C<forward> is similar to a method call. The main differences are that
598 it wraps the call in an C<eval> to allow exception handling; it
599 automatically passes along the context object (C<$c> or C<$context>);
600 and it allows profiling of each call (displayed in the log with
604 my ( $self, $c ) = @_;
605 $c->stash->{message} = 'Hello World!';
606 $c->forward('check_message'); # $c is automatically included
609 sub check_message : Private {
610 my ( $self, $c ) = @_;
611 return unless $c->stash->{message};
612 $c->forward('show_message');
615 sub show_message : Private {
616 my ( $self, $c ) = @_;
617 $c->res->body( $c->stash->{message} );
620 A C<forward> does not create a new request, so your request
621 object (C<$c-E<gt>req>) will remain unchanged. This is a
622 key difference between using C<forward> and issuing a
625 You can pass new arguments to a C<forward> by adding them
626 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
627 will be changed for the duration of the C<forward> only; upon
628 return, the original value of C<$c-E<gt>req-E<gt>args> will
632 my ( $self, $c ) = @_;
633 $c->stash->{message} = 'Hello World!';
634 $c->forward('check_message',[qw/test1/]);
635 # now $c->req->args is back to what it was before
638 sub check_message : Private {
639 my ( $self, $c ) = @_;
640 my $first_argument = $c->req->args->[0]; # now = 'test1'
644 As you can see from these examples, you can just use the method name as
645 long as you are referring to methods in the same controller. If you want
646 to forward to a method in another controller, or the main application,
647 you will have to refer to the method by absolute path.
649 $c->forward('/my/controller/action');
650 $c->forward('/default'); # calls default in main application
652 Here are some examples of how to forward to classes and methods.
655 my ( $self, $c ) = @_;
656 $c->forward(qw/MyApp::Model::Hello say_hello/);
660 my ( $self, $c ) = @_;
661 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
664 package MyApp::Model::Hello;
667 my ( $self, $c ) = @_;
668 $c->res->body('Hello World!');
672 my ( $self, $c ) = @_;
673 $c->res->body('Goodbye World!');
676 Note that C<forward> returns to the calling action and continues
677 processing after the action finishes. If you want all further processing
678 in the calling action to stop, use C<detach> instead, which will execute
679 the C<detach>ed action and not return to the calling sub. In both cases,
680 Catalyst will automatically try to call process() if you omit the
685 Catalyst has an uncommonly flexible component system. You can define as
686 many L</Models>, L</Views>, and L</Controllers> as you like.
688 All components must inherit from L<Catalyst::Base>, which provides a
689 simple class structure and some common class methods like C<config> and
690 C<new> (constructor).
692 package MyApp::Controller::Catalog;
695 use base 'Catalyst::Base';
697 __PACKAGE__->config( foo => 'bar' );
701 You don't have to C<use> or otherwise register Models, Views, and
702 Controllers. Catalyst automatically discovers and instantiates them
703 when you call C<setup> in the main application. All you need to do is
704 put them in directories named for each Component type. Notice that you
705 can use some very terse aliases for each one.
709 =item * B<MyApp/Model/>
713 =item * B<MyApp/View/>
717 =item * B<MyApp/Controller/>
725 To show how to define views, we'll use an already-existing base class for the
726 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
727 inherit from this class:
729 package MyApp::View::TT;
732 use base 'Catalyst::View::TT';
736 (You can also generate this automatically by using the helper script:
738 script/myapp_create.pl view TT TT
740 where the first C<TT> tells the script that the name of the view should
741 be C<TT>, and the second that it should be a Template Toolkit view.)
743 This gives us a process() method and we can now just do
744 $c->forward('MyApp::View::TT') to render our templates. The base class
745 makes process() implicit, so we don't have to say
746 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
749 my ( $self, $c ) = @_;
750 $c->stash->{template} = 'hello.tt';
754 my ( $self, $c ) = @_;
755 $c->forward('MyApp::View::TT');
758 You normally render templates at the end of a request, so it's a perfect
759 use for the global C<end> action.
761 Also, be sure to put the template under the directory specified in
762 C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our
763 eyecandy debug screen. ;)
767 To show how to define models, again we'll use an already-existing base
768 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
769 We'll also need L<DBIx::Class::Schema::Loader>.
771 But first, we need a database.
775 id INTEGER PRIMARY KEY,
780 id INTEGER PRIMARY KEY,
781 foo INTEGER REFERENCES foo,
785 INSERT INTO foo (data) VALUES ('TEST!');
788 % sqlite /tmp/myapp.db < myapp.sql
790 Now we can create a DBIC::SchemaLoader component for this database.
792 script/myapp_create.pl model DBIC DBIC::SchemaLoader 'dbi:SQLite:/tmp/myapp.db'
794 L<DBIx::Class::Schema::Loader> automatically loads table layouts and
795 relationships. Use the stash to pass data to your templates.
797 We add the following to MyApp/Controller/Root.pm
800 my ( $self, $c, $id ) = @_;
802 $c->stash->{item} = $c->model('DBIC::Foo')->find($id);
808 my ( $self, $c ) = @_;
810 $c->stash->{template} ||= 'index.tt';
811 $c->forward( $c->view('TT') );
814 We then create a new template file "root/index.tt" containing:
816 The Id's data is [% item.data %]
818 Models do not have to be part of your Catalyst application; you
819 can always call an outside module that serves as your Model:
823 my ( $self, $c ) = @_;
825 $c->stash->{template} = 'list.tt';
827 use Some::Outside::DBIC::Module;
828 my @records = Some::Outside::DBIC::Module->search({
832 $c->stash->{records} = \@records;
835 But by using a Model that is part of your Catalyst application, you gain
836 several things: you don't have to C<use> each component, Catalyst will
837 find and load it automatically at compile-time; you can C<forward> to
838 the module, which can only be done to Catalyst components; and only
839 Catalyst components can be fetched with
840 C<$c-E<gt>model('SomeModel')>.
842 Happily, since many people have existing Model classes that they
843 would like to use with Catalyst (or, conversely, they want to
844 write Catalyst models that can be used outside of Catalyst, e.g.
845 in a cron job), it's trivial to write a simple component in
846 Catalyst that slurps in an outside Model:
848 package MyApp::Model::DB;
849 use base qw/Catalyst::Model::DBIC::Schema/;
851 schema_class => 'Some::DBIC::Schema',
852 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
856 and that's it! Now C<Some::DBIC::Schema> is part of your
857 Cat app as C<MyApp::Model::DB>.
861 Multiple controllers are a good way to separate logical domains of your
864 package MyApp::Controller::Login;
866 sub sign-in : Local { }
867 sub new-password : Local { }
868 sub sign-out : Local { }
870 package MyApp::Controller::Catalog;
875 package MyApp::Controller::Cart;
878 sub update : Local { }
879 sub order : Local { }
883 Catalyst has a built-in http server for testing! (Later, you can easily
884 use a more powerful server, e.g. Apache/mod_perl, in a production
887 Start your application on the command line...
889 script/myapp_server.pl
891 ...then visit http://localhost:3000/ in a browser to view the output.
893 You can also do it all from the command line:
895 script/myapp_test.pl http://localhost/
903 Join #catalyst on irc.perl.org.
907 http://lists.rawmode.org/mailman/listinfo/catalyst
908 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
912 Sebastian Riedel, C<sri@oook.de>
913 David Naughton, C<naughton@umn.edu>
914 Marcus Ramberg, C<mramberg@cpan.org>
915 Jesse Sheidlower, C<jester@panix.com>
916 Danijel Milicevic, C<me@danijel.de>
920 This program is free software, you can redistribute it and/or modify it
921 under the same terms as Perl itself.