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>.
11 For a systematic step-by-step introduction to writing an application
12 with Catalyst, see L<Catalyst::Manual::Tutorial>.
14 =head2 What is Catalyst?
16 Catalyst is an elegant web application framework, extremely flexible
17 yet extremely simple. It's similar to Ruby on Rails, Spring (Java), and
18 L<Maypole|Maypole>, upon which it was originally based. Its most
19 important design philosphy is to provide easy access to all the tools
20 you need to develop web applications, with few restrictions on how you
21 need to use these tools. However, this does mean that it is always
22 possible to do things in a different way. Other web frameworks are
23 I<initially> simpler to use, but achieve this by locking the programmer
24 into a single set of tools. Catalyst's emphasis on flexibility means
25 that you have to think more to use it. We view this as a feature. For
26 example, this leads to Catalyst being more suited to system integration
27 tasks than other web frameworks.
31 Catalyst follows the Model-View-Controller (MVC) design pattern,
32 allowing you to easily separate concerns, like content, presentation,
33 and flow control, into separate modules. This separation allows you to
34 modify code that handles one concern without affecting code that handles
35 the others. Catalyst promotes the re-use of existing Perl modules that
36 already handle common web application concerns well.
38 Here's how the Model, View, and Controller map to those concerns, with
39 examples of well-known Perl modules you may want to use for each.
45 Access and modify content (data). L<DBIx::Class>, L<Class::DBI>,
46 L<Xapian>, L<Net::LDAP>...
50 Present content to the user. L<Template Toolkit|Template>,
51 L<Mason|HTML::Mason>, L<HTML::Template>...
55 Control the whole request phase, check parameters, dispatch actions, flow
56 control. Catalyst itself!
60 If you're unfamiliar with MVC and design patterns, you may want to
61 check out the original book on the subject, I<Design Patterns>, by
62 Gamma, Helm, Johnson, and Vlissides, also known as the Gang of Four
63 (GoF). Many, many web application frameworks are based on MVC, which
64 is becoming a popular design paradigm for the world wide web.
68 Catalyst is much more flexible than many other frameworks. Rest assured
69 you can use your favorite Perl modules with Catalyst.
73 =item * B<Multiple Models, Views, and Controllers>
75 To build a Catalyst application, you handle each type of concern inside
76 special modules called L</Components>. Often this code will be very
77 simple, just calling out to Perl modules like those listed above under
78 L</MVC>. Catalyst handles these components in a very flexible way. Use
79 as many Models, Views, and Controllers as you like, using as many
80 different Perl modules as you like, all in the same application. Want to
81 manipulate multiple databases, and retrieve some data via LDAP? No
82 problem. Want to present data from the same Model using L<Template
83 Toolkit|Template> and L<PDF::Template>? Easy.
85 =item * B<Reuseable Components>
87 Not only does Catalyst promote the re-use of already existing Perl
88 modules, it also allows you to re-use your Catalyst components in
89 multiple Catalyst applications.
91 =item * B<Unrestrained URL-to-Action Dispatching>
93 Catalyst allows you to dispatch any URLs to any application L</Actions>,
94 even through regular expressions! Unlike most other frameworks, it
95 doesn't require mod_rewrite or class and method names in URLs.
97 With Catalyst you register your actions and address them directly. For
101 my ( $self, $context ) = @_;
102 $context->response->body('Hello World!');
105 Now http://localhost:3000/hello prints "Hello World!".
107 Note that actions with the C< :Local > attribute are equivalent to
108 using a C<:Path('action_name') > attribute, so our action could be
111 sub hi : Path('hello') {
112 my ( $self, $context ) = @_;
113 $context->response->body('Hello World!');
117 =item * B<Support for CGI, mod_perl, Apache::Request, FastCGI>
119 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Another
120 interesting engine is L<Catalyst::Engine::HTTP::Prefork> - available from CPAN
121 separately - which will turn the built server into a fully fledged production
122 ready server (although you'll probably want to run it behind a front end proxy
123 if you end up using it).
129 The best part is that Catalyst implements all this flexibility in a very
134 =item * B<Building Block Interface>
136 Components interoperate very smoothly. For example, Catalyst
137 automatically makes a L</Context> object available to every
138 component. Via the context, you can access the request object, share
139 data between components, and control the flow of your
140 application. Building a Catalyst application feels a lot like snapping
141 together toy building blocks, and everything just works.
143 =item * B<Component Auto-Discovery>
145 No need to C<use> all of your components. Catalyst automatically finds
148 =item * B<Pre-Built Components for Popular Modules>
150 See L<Catalyst::Model::DBIC::Schema> for L<DBIx::Class>, or
151 L<Catalyst::View::TT> for L<Template Toolkit|Template>.
153 =item * B<Built-in Test Framework>
155 Catalyst comes with a built-in, lightweight http server and test
156 framework, making it easy to test applications from the web browser,
157 and the command line.
159 =item * B<Helper Scripts>
161 Catalyst provides helper scripts to quickly generate running starter
162 code for components and unit tests. Install L<Catalyst::Devel> and see
169 Here's how to install Catalyst and get a simple application up and
170 running, using the helper scripts described above.
174 Installation of Catalyst should be straightforward:
176 # perl -MCPAN -e 'install Catalyst::Runtime'
177 # perl -MCPAN -e 'install Catalyst::Devel'
184 $ script/myapp_create.pl controller Library::Login
186 =head4 Frank Speiser's Amazon EC2 Catalyst SDK
188 There are currently two flavors of publicly available Amazon Machine
189 Images (AMI) that include all the elements you'd need to begin
190 developing in a fully functional Catalyst environment within
192 L<Catalyst::Manual::Installation|Catalyst::Manual::Installation> for
198 $ script/myapp_server.pl
200 Now visit these locations with your favorite browser or user agent to see
203 (NOTE: Although we create a controller here, we don't actually use it.
204 Both of these URLs should take you to the welcome page.)
209 =item http://localhost:3000/
211 =item http://localhost:3000/library/login/
217 Let's see how Catalyst works, by taking a closer look at the components
218 and other parts of a Catalyst application.
222 Catalyst has an uncommonly flexible component system. You can define as
223 many L</Models>, L</Views>, and L</Controllers> as you like. As discussed
224 previously, the general idea is that the View is responsible for the
225 output of data to the user (typically via a web browser, but a View can
226 also generate PDFs or e-mails, for example); the Model is responsible
227 for providing data (typically from a relational database); and the
228 Controller is responsible for interacting with the user and deciding
229 how user input determines what actions the application takes.
231 In the world of MVC, there are frequent discussions and disagreements
232 about the nature of each element - whether certain types of logic
233 belong in the Model or the Controller, etc. Catalyst's flexibility
234 means that this decision is entirely up to you, the programmer;
235 Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
236 a general discussion of these issues.
238 Model, View and Controller components must inherit from L<Catalyst::Model>,
239 L<Catalyst::View> and L<Catalyst::Controller>, respectively. These, in turn, inherit
240 from L<Catalyst::Component> which provides a simple class structure and some
241 common class methods like C<config> and C<new> (constructor).
243 package MyApp::Controller::Catalog;
245 use namespace::autoclean;
247 BEGIN { extends 'Catalyst::Controller' }
249 __PACKAGE__->config( foo => 'bar' );
253 You don't have to C<use> or otherwise register Models, Views, and
254 Controllers. Catalyst automatically discovers and instantiates them
255 when you call C<setup> in the main application. All you need to do is
256 put them in directories named for each Component type. You can use a
257 short alias for each one.
261 =item * B<MyApp/Model/>
265 =item * B<MyApp/View/>
269 =item * B<MyApp/Controller/>
275 In older versions of Catalyst, the recommended practice (and the one
276 automatically created by helper scripts) was to name the directories
277 C<M/>, C<V/>, and C<C/>. Though these still work, they are deprecated
278 and we now recommend the use of the full names.
282 To show how to define views, we'll use an already-existing base class for the
283 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
284 inherit from this class:
286 package MyApp::View::TT;
289 use base 'Catalyst::View::TT';
293 (You can also generate this automatically by using the helper script:
295 script/myapp_create.pl view TT TT
297 where the first C<TT> tells the script that the name of the view should
298 be C<TT>, and the second that it should be a Template Toolkit view.)
300 This gives us a process() method and we can now just do
301 $c->forward('MyApp::View::TT') to render our templates. The base class
302 makes process() implicit, so we don't have to say
303 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
306 my ( $self, $c ) = @_;
307 $c->stash->{template} = 'hello.tt';
311 my ( $self, $c ) = @_;
312 $c->forward( $c->view('TT') );
315 You normally render templates at the end of a request, so it's a perfect
316 use for the global C<end> action.
318 In practice, however, you would use a default C<end> action as supplied
319 by L<Catalyst::Action::RenderView>.
321 Also, be sure to put the template under the directory specified in
322 C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
327 Models are providers of data. This data could come from anywhere - a
328 search engine index, a spreadsheet, the file system - but typically a
329 Model represents a database table. The data source does not
330 intrinsically have much to do with web applications or Catalyst - it
331 could just as easily be used to write an offline report generator or a
334 To show how to define models, again we'll use an already-existing base
335 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
336 We'll also need L<DBIx::Class::Schema::Loader>.
338 But first, we need a database.
342 id INTEGER PRIMARY KEY,
347 id INTEGER PRIMARY KEY,
348 foo INTEGER REFERENCES foo,
352 INSERT INTO foo (data) VALUES ('TEST!');
354 % sqlite3 /tmp/myapp.db < myapp.sql
356 Now we can create a DBIC::Schema model for this database.
358 script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
360 L<DBIx::Class::Schema::Loader> can automatically load table layouts and
361 relationships, and convert them into a static schema definition
362 C<MySchema>, which you can edit later.
364 Use the stash to pass data to your templates.
366 We add the following to MyApp/Controller/Root.pm
369 my ( $self, $c, $id ) = @_;
371 $c->stash->{item} = $c->model('MyModel::Foo')->find($id);
377 my ( $self, $c ) = @_;
379 $c->stash->{template} ||= 'index.tt';
380 $c->forward( $c->view('TT') );
383 We then create a new template file "root/index.tt" containing:
385 The Id's data is [% item.data %]
387 Models do not have to be part of your Catalyst application; you
388 can always call an outside module that serves as your Model:
392 my ( $self, $c ) = @_;
394 $c->stash->{template} = 'list.tt';
396 use Some::Outside::Database::Module;
397 my @records = Some::Outside::Database::Module->search({
398 artist => 'Led Zeppelin',
401 $c->stash->{records} = \@records;
404 But by using a Model that is part of your Catalyst application, you
405 gain several things: you don't have to C<use> each component, Catalyst
406 will find and load it automatically at compile-time; you can
407 C<forward> to the module, which can only be done to Catalyst
408 components. Only Catalyst components can be fetched with
409 C<$c-E<gt>model('SomeModel')>.
411 Happily, since many people have existing Model classes that they
412 would like to use with Catalyst (or, conversely, they want to
413 write Catalyst models that can be used outside of Catalyst, e.g.
414 in a cron job), it's trivial to write a simple component in
415 Catalyst that slurps in an outside Model:
417 package MyApp::Model::DB;
418 use base qw/Catalyst::Model::DBIC::Schema/;
420 schema_class => 'Some::DBIC::Schema',
421 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
425 and that's it! Now C<Some::DBIC::Schema> is part of your
426 Cat app as C<MyApp::Model::DB>.
428 Within Catalyst, the common approach to writing a model for your
429 application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
430 bunch of XMLs, or anything really) with an object that contains
431 configuration data, convenience methods, and so forth. Thus you
432 will in effect have two models - a wrapper model that knows something
433 about Catalyst and your web application, and a generic model that is
434 totally independent of these needs.
436 Technically, within Catalyst a model is a B<component> - an instance of
437 the model's class belonging to the application. It is important to
438 stress that the lifetime of these objects is per application, not per
441 While the model base class (L<Catalyst::Model>) provides things like
442 C<config> to better integrate the model into the application, sometimes
443 this is not enough, and the model requires access to C<$c> itself.
445 Situations where this need might arise include:
451 Interacting with another model
455 Using per-request data to control behavior
459 Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
463 From a style perspective it's usually considered bad form to make your
464 model "too smart" about things - it should worry about business logic
465 and leave the integration details to the controllers. If, however, you
466 find that it does not make sense at all to use an auxillary controller
467 around the model, and the model's need to access C<$c> cannot be
468 sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
472 Multiple controllers are a good way to separate logical domains of your
475 package MyApp::Controller::Login;
477 use base qw/Catalyst::Controller/;
479 sub login : Path("login") { }
480 sub new_password : Path("new-password") { }
481 sub logout : Path("logout") { }
483 package MyApp::Controller::Catalog;
485 use base qw/Catalyst::Controller/;
490 package MyApp::Controller::Cart;
492 use base qw/Catalyst::Controller/;
495 sub update : Local { }
496 sub order : Local { }
498 Note that you can also supply attributes via the Controller's config so
499 long as you have at least one attribute on a subref to be exported
500 (:Action is commonly used for this) - for example the following is
501 equivalent to the same controller above:
503 package MyApp::Controller::Login;
505 use base qw/Catalyst::Controller/;
509 'sign_in' => { Path => 'sign-in' },
510 'new_password' => { Path => 'new-password' },
511 'sign_out' => { Path => 'sign-out' },
515 sub sign_in : Action { }
516 sub new_password : Action { }
517 sub sign_out : Action { }
519 =head3 ACCEPT_CONTEXT
521 Whenever you call $c->component("Foo") you get back an object - the
522 instance of the model. If the component supports the C<ACCEPT_CONTEXT>
523 method instead of returning the model itself, the return value of C<<
524 $model->ACCEPT_CONTEXT( $c ) >> will be used.
526 This means that whenever your model/view/controller needs to talk to
527 C<$c> it gets a chance to do this when it's needed.
529 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
530 with the context object set, or it will return a thin wrapper that contains
531 C<$c> and delegates to the per-application model object.
533 Generally it's a bad idea to expose the context object (C<$c>) in your
534 model or view code. Instead you use the C<ACCEPT_CONTEXT> subroutine
535 to grab the bits of the context object that you need, and provide
536 accessors to them in the model. This ensures that C<$c> is only in
537 scope where it is neaded which reduces maintenance and debugging
538 headaches. So, if for example you needed two
539 L<Catalyst::Model::DBIC::Schema> models in the same Catalyst model
540 code, you might do something like this:
542 __PACKAGE__->mk_accessors(qw(model1_schema model2_schema));
544 my ( $self, $c, @extra_arguments ) = @_;
545 $self = bless({ %$self,
546 model1_schema => $c->model('Model1')->schema,
547 model2_schema => $c->model('Model2')->schema
552 This effectively treats $self as a B<prototype object> that gets a new
553 parameter. C<@extra_arguments> comes from any trailing arguments to
554 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...)
555 >>, C<< $c->view(...) >> etc).
557 In a subroutine in the model code, we can then do this:
561 my $schema1 = $self->model1_schema;
562 my $schema2 = $self->model2_schema;
566 Note that we still want the Catalyst models to be a thin wrapper
567 around classes that will work independently of the Catalyst
568 application to promote reusability of code. Here we might just want
569 to grab the $c->model('DB')->schema so as to get the connection
570 information from the Catalyst application's configuration for example.
572 The life time of this value is B<per usage>, and not per request. To
573 make this per request you can use the following technique:
575 Add a field to C<$c>, like C<my_model_instance>. Then write your
576 C<ACCEPT_CONTEXT> method to look like this:
579 my ( $self, $c ) = @_;
581 if ( my $per_request = $c->my_model_instance ) {
584 my $new_instance = bless { %$self, c => $c }, ref($self);
585 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
586 $c->my_model_instance( $new_instance );
587 return $new_instance;
591 For a similar technique to grab a new component instance on each
592 request, see L<Catalyst::Component::InstancePerContext>.
594 =head3 Application Class
596 In addition to the Model, View, and Controller components, there's a
597 single class that represents your application itself. This is where you
598 configure your application, load plugins, and extend Catalyst.
603 use parent qw/Catalyst/;
604 use Catalyst qw/-Debug ConfigLoader Static::Simple/;
606 name => 'My Application',
608 # You can put anything else you want in here:
609 my_configuration_variable => 'something',
613 In older versions of Catalyst, the application class was where you put
614 global actions. However, as of version 5.66, the recommended practice is
615 to place such actions in a special Root controller (see L</Actions>,
616 below), to avoid namespace collisions.
622 The name of your application.
626 Optionally, you can specify a B<root> parameter for templates and static
627 data. If omitted, Catalyst will try to auto-detect the directory's
628 location. You can define as many parameters as you want for plugins or
629 whatever you need. You can access them anywhere in your application via
630 C<$context-E<gt>config-E<gt>{$param_name}>.
634 Catalyst automatically blesses a Context object into your application
635 class and makes it available everywhere in your application. Use the
636 Context to directly interact with Catalyst and glue your L</Components>
637 together. For example, if you need to use the Context from within a
638 Template Toolkit template, it's already there:
640 <h1>Welcome to [% c.config.name %]!</h1>
642 As illustrated in our URL-to-Action dispatching example, the Context is
643 always the second method parameter, behind the Component object
644 reference or class name itself. Previously we called it C<$context> for
645 clarity, but most Catalyst developers just call it C<$c>:
648 my ( $self, $c ) = @_;
649 $c->res->body('Hello World!');
652 The Context contains several important objects:
656 =item * L<Catalyst::Request>
661 The request object contains all kinds of request-specific information, like
662 query parameters, cookies, uploads, headers, and more.
664 $c->req->params->{foo};
665 $c->req->cookies->{sessionid};
666 $c->req->headers->content_type;
668 $c->req->uri_with( { page = $pager->next_page } );
670 =item * L<Catalyst::Response>
675 The response is like the request, but contains just response-specific
678 $c->res->body('Hello World');
679 $c->res->status(404);
680 $c->res->redirect('http://oook.de');
688 =item * L<Catalyst::Log>
691 $c->log->debug('Something happened');
692 $c->log->info('Something you should know');
697 $c->stash->{foo} = 'bar';
698 $c->stash->{baz} = {baz => 'qox'};
699 $c->stash->{fred} = [qw/wilma pebbles/];
705 The last of these, the stash, is a universal hash for sharing data among
706 application components. For an example, we return to our 'hello' action:
709 my ( $self, $c ) = @_;
710 $c->stash->{message} = 'Hello World!';
711 $c->forward('show_message');
714 sub show_message : Private {
715 my ( $self, $c ) = @_;
716 $c->res->body( $c->stash->{message} );
719 Note that the stash should be used only for passing data in an
720 individual request cycle; it gets cleared at a new request. If you need
721 to maintain persistent data, use a session. See
722 L<Catalyst::Plugin::Session> for a comprehensive set of
723 Catalyst-friendly session-handling tools.
727 You've already seen some examples of actions in this document:
728 subroutines with C<:Path> and C<:Local> attributes attached.
729 Here, we explain what actions are and how these attributes affect
732 When Catalyst processes a webpage request, it looks for actions to
733 take that will deal with the incoming request and produce a response
734 such as a webpage. You create these actions for your application by
735 writing subroutines within your controller and marking them with
736 special attributes. The attributes, the namespace, and the function
737 name determine when Catalyst will call the subroutine.
739 These action subroutines call certain functions to say what response
740 the webserver will give to the web request. They can also tell
741 Catalyst to run other actions on the request (one example of this is
742 called forwarding the request; this is discussed later).
744 Action subroutines must have a special attribute on to show that they
745 are actions - as well as marking when to call them, this shows that
746 they take a specific set of arguments and behave in a specific way.
747 At startup, Catalyst looks for all the actions in controllers,
748 registers them and creates L<Catalyst::Action> objects describing
749 them. When requests come in, Catalyst chooses which actions should be
750 called to handle the request.
752 (Occasionally, you might use the action objects directly, but in
753 general, when we talk about actions, we're talking about the
754 subroutines in your application that do things to process a request.)
756 You can choose one of several attributes for action subroutines; these
757 specify which requests are processed by that subroutine. Catalyst
758 will look at the URL it is processing, and the actions that it has
759 found, and automatically call the actions it finds that match the
760 circumstances of the request.
762 The URL (for example http://localhost:3000/foo/bar) consists of two
763 parts, the base, describing how to connect to the server
764 (http://localhost:3000/ in this example) and the path, which the
765 server uses to decide what to return (foo/bar). Please note that the
766 trailing slash after the hostname[:port] always belongs to base and
767 not to the path. Catalyst uses only the path part when trying to find
770 Depending on the type of action used, the URLs may match a combination
771 of the controller namespace, the arguments passed to the action
772 attribute, and the name of the subroutine.
776 =item * B<Controller namespaces>
778 The namespace is a modified form of the component's class (package)
779 name. This modified class name excludes the parts that have a
780 pre-defined meaning in Catalyst ("MyApp::Controller" in the above
781 example), replaces "::" with "/", and converts the name to lower case.
782 See L</Components> for a full explanation of the pre-defined meaning
783 of Catalyst component class names.
785 =item * B<Overriding the namespace>
787 Note that I<< __PACKAGE__->config->(namespace => ... ) >> can be used to override the
788 current namespace when matching. So:
790 package MyApp::Controller::Example;
792 would normally use 'example' as its namespace for matching, but if
793 this is specially overridden with
795 __PACKAGE__->config( namespace => 'thing' );
797 it matches using the namespace 'thing' instead.
799 =item * B<Application Wide Actions>
801 MyApp::Controller::Root, as created by the catalyst.pl script, will
802 typically contain actions which are called for the top level of the
803 application (e.g. http://localhost:3000/ ):
805 package MyApp::Controller::Root;
806 use base 'Catalyst::Controller';
807 # Sets the actions in this controller to be registered with no prefix
808 # so they function identically to actions created in MyApp.pm
809 __PACKAGE__->config( namespace => '');
811 my ( $self, $context ) = @_;
812 $context->response->status(404);
813 $context->response->body('404 not found');
820 __PACKAGE__->config( namespace => '' );
822 makes the controller act as if its namespace is empty. As you'll see
823 below, an empty namespace makes many of the URL-matching attributes,
824 such as :Path, :Local and :Global matches, match at the start of the
831 Catalyst supports several types of actions. These mainly correspond
832 to ways of matching a URL to an action subroutine. Internally, these
833 matching types are implemented by L<Catalyst::DispatchType>-derived
834 classes; the documentation there can be helpful in seeing how they
837 They will all attempt to match the start of the path. The remainder
838 of the path is passed as arguments.
842 =item * Namespace-prefixed (C<:Local>)
844 package MyApp::Controller::My::Controller;
847 Matches any URL beginning with> http://localhost:3000/my/controller/foo. The namespace and
848 subroutine name together determine the path.
850 =item * Root-level (C<:Global>)
852 package MyApp::Controller::Foo;
855 Matches http://localhost:3000/foo - that is, the action is mapped
856 directly to the controller namespace, ignoring the function name.
858 C<:Global> always matches from root: it is sugar for C<:Path('/methodname')>.
859 C<:Local> is simply sugar for C<:Path('methodname')>, which takes the package
860 namespace as described above.
862 package MyApp::Controller::Root;
863 __PACKAGE__->config( namespace => '');
866 Use whichever makes the most sense for your application.
868 =item * Changing handler behaviour: eating arguments (C<:Args>)
870 Args is not an action type per se, but an action modifier - it adds a
871 match restriction to any action it's provided to, additionally
872 requiring as many path parts as are specified for the action to be
873 matched. For example, in MyApp::Controller::Foo,
877 would match any URL starting /foo/bar. To restrict this you can do
879 sub bar :Local :Args(1)
881 to only match URLs starting /foo/bar/* - with one additional path
882 element required after 'bar'.
884 NOTE that adding C<:Args(0)> and missing out :Args completely are B<not>
887 C<:Args(0)> means that no arguments are taken. Thus, the URL and path must
890 No :Args at all means that B<any number> of arguments are taken. Thus, any
891 URL that B<starts with> the controller's path will match. Obviously, this means
892 you cannot chain from an action that does not specify args, as the next action
893 in the chain will be swallowed as an arg to the first!
896 =item * Literal match (C<:Path>)
898 C<Path> actions match things starting with a precise specified path,
901 C<Path> actions without a leading forward slash match a specified path
902 relative to their current namespace. This example matches URLs
903 starting http://localhost:3000/my/controller/foo/bar :
905 package MyApp::Controller::My::Controller;
906 sub bar : Path('foo/bar') { }
908 C<Path> actions B<with> a leading slash ignore their namespace, and
909 match from the start of the URL path. Example:
911 package MyApp::Controller::My::Controller;
912 sub bar : Path('/foo/bar') { }
914 This matches URLs beginning http://localhost:3000/foo/bar.
916 Empty C<Path> definitions match on the namespace only, exactly like
919 package MyApp::Controller::My::Controller;
922 The above code matches http://localhost:3000/my/controller.
924 Actions with the C<:Local> attribute are similarly equivalent to
925 C<:Path('action_name')>:
931 sub foo : Path('foo') { }
933 =item * Pattern-match (C<:Regex> and C<:LocalRegex>)
935 package MyApp::Controller::My::Controller;
936 sub bar : Regex('^item(\d+)/order(\d+)$') { }
938 This matches any URL that matches the pattern in the action key, e.g.
939 http://localhost:3000/item23/order42. The '' around the regexp is
940 optional, but perltidy likes it. :)
942 C<:Regex> matches act globally, i.e. without reference to the namespace
943 from which they are called. So the above will B<not> match
944 http://localhost:3000/my/controller/item23/order42 - use a
945 C<:LocalRegex> action instead.
947 package MyApp::Controller::My::Controller;
948 sub bar : LocalRegex('^widget(\d+)$') { }
950 C<:LocalRegex> actions act locally, i.e. the namespace is matched
951 first. The above example would match urls like
952 http://localhost:3000/my/controller/widget23.
954 If you omit the "C<^>" from either sort of regex, then it will match any depth
957 package MyApp::Controller::Catalog;
958 sub bar : LocalRegex('widget(\d+)$') { }
960 This differs from the previous example in that it will match
961 http://localhost:3000/my/controller/foo/widget23 - and a number of
964 For both C<:LocalRegex> and C<:Regex> actions, if you use capturing
965 parentheses to extract values within the matching URL, those values
966 are available in the C<$c-E<gt>req-E<gt>captures> array. In the above
967 example, "widget23" would capture "23" in the above example, and
968 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to
969 pass arguments at the end of your URL, you must use regex action
970 keys. See L</URL Path Handling> below.
972 =item * Chained handlers (C<:Chained>)
974 Catalyst also provides a method to build and dispatch chains of actions,
977 sub catalog : Chained : CaptureArgs(1) {
978 my ( $self, $c, $arg ) = @_;
982 sub item : Chained('catalog') : Args(1) {
983 my ( $self, $c, $arg ) = @_;
987 to handle a C</catalog/*/item/*> path. Matching actions are called
988 one after another - C<catalog()> gets called and handed one path
989 element, then C<item()> gets called with another one. For further
990 information about this dispatch type, please see
991 L<Catalyst::DispatchType::Chained>.
995 sub foo : Private { }
997 This will never match a URL - it provides a private action which can
998 be called programmatically from within Catalyst, but is never called
999 automatically due to the URL being requested.
1001 Catalyst's C<:Private> attribute is exclusive and doesn't work with other
1002 attributes (so will not work combined with C<:Path> or C<:Chained>
1003 attributes, for instance).
1005 Private actions can only be executed explicitly from inside a Catalyst
1006 application. You might do this in your controllers by calling
1007 catalyst methods such as C<forward> or C<detach> to fire them:
1013 See L</Flow Control> for a full explanation of how you can pass
1014 requests on to other actions. Note that, as discussed there, when
1015 forwarding from another component, you must use the absolute path to
1016 the method, so that a private C<bar> method in your
1017 C<MyApp::Controller::Catalog::Order::Process> controller must, if
1018 called from elsewhere, be reached with
1019 C<$c-E<gt>forward('/catalog/order/process/bar')>.
1023 B<Note:> After seeing these examples, you probably wonder what the
1024 point is of defining subroutine names for regex and path
1025 actions. However, every public action is also a private one with a
1026 path corresponding to its namespace and subroutine name, so you have
1027 one unified way of addressing components in your C<forward>s.
1029 =head4 Built-in special actions
1031 If present, the special actions C< index >, C< auto >, C<begin>,
1032 C<end> and C< default > are called at certain points in the request
1035 In response to specific application states, Catalyst will automatically
1036 call these built-in actions in your application class:
1040 =item * B<default : Path>
1042 This is called when no other action matches. It could be used, for
1043 example, for displaying a generic frontpage for the main app, or an
1044 error page for individual controllers. B<Note>: in older Catalyst
1045 applications you will see C<default : Private> which is roughly
1046 speaking equivalent.
1049 =item * B<index : Path : Args (0) >
1051 C<index> is much like C<default> except that it takes no arguments and
1052 it is weighted slightly higher in the matching process. It is useful
1053 as a static entry point to a controller, e.g. to have a static welcome
1054 page. Note that it's also weighted higher than Path. Actually the sub
1055 name C<index> can be called anything you want. The sub attributes are
1056 what determines the behaviour of the action. B<Note>: in older
1057 Catalyst applications, you will see C<index : Private> used, which is
1058 roughly speaking equivalent.
1060 =item * B<begin : Private>
1062 Called at the beginning of a request, once the controller that will
1063 run has been identified, but before any URL-matching actions are
1064 called. Catalyst will call the C<begin> function in the controller
1065 which contains the action matching the URL.
1067 =item * B<end : Private>
1069 Called at the end of a request, after all URL-matching actions are called.
1070 Catalyst will call the C<end> function in the controller
1071 which contains the action matching the URL.
1073 =item * B<auto : Private>
1075 In addition to the normal built-in actions, you have a special action
1076 for making chains, C<auto>. C<auto> actions will be run after any
1077 C<begin>, but before your URL-matching action is processed. Unlike the other
1078 built-ins, multiple C<auto> actions can be called; they will be
1079 called in turn, starting with the application class and going through
1080 to the most specific class.
1084 =head4 Built-in actions in controllers/autochaining
1086 package MyApp::Controller::Foo;
1087 sub begin : Private { }
1088 sub default : Path { }
1091 You can define built-in actions within your controllers as well as on
1092 your application class. In other words, for each of the three built-in
1093 actions above, only one will be run in any request cycle. Thus, if
1094 C<MyApp::Controller::Catalog::begin> exists, it will be run in place
1095 of C<MyApp::begin> if you're in the C<catalog> namespace, and
1096 C<MyApp::Controller::Catalog::Order::begin> would override this in
1099 sub auto : Private { }
1101 C<auto>, however, doesn't override like this: providing they exist,
1102 C<MyApp::Controller::Root::auto>, C<MyApp::Controller::Catalog::auto> and
1103 C<MyApp::Catalog::Order::auto> would be called in turn.
1105 Here are some examples of the order in which the various built-ins
1110 =item for a request for C</foo/foo>
1112 MyApp::Controller::Foo::auto
1113 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
1114 MyApp::Controller::Foo::end
1116 =item for a request for C</foo/bar/foo>
1118 MyApp::Controller::Foo::Bar::begin
1119 MyApp::Controller::Foo::auto
1120 MyApp::Controller::Foo::Bar::auto
1121 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
1122 MyApp::Controller::Foo::Bar::end
1126 The C<auto> action is also distinguished by the fact that you can break
1127 out of the processing chain by returning 0. If an C<auto> action returns
1128 0, any remaining actions will be skipped, except for C<end>. So, for the
1129 request above, if the first auto returns false, the chain would look
1134 =item for a request for C</foo/bar/foo> where first C<auto> returns
1137 MyApp::Controller::Foo::Bar::begin
1138 MyApp::Controller::Foo::auto # returns false, skips some calls:
1139 # MyApp::Controller::Foo::Bar::auto - never called
1140 # MyApp::Controller::Foo::Bar::foo - never called
1141 MyApp::Controller::Foo::Bar::end
1143 You can also C<die> in the auto action; in that case, the request will
1144 go straight to the finalize stage, without processing further
1145 actions. So in the above example, C<MyApp::Controller::Foo::Bar::end>
1150 An example of why one might use C<auto> is an authentication action:
1151 you could set up a C<auto> action to handle authentication in your
1152 application class (which will always be called first), and if
1153 authentication fails, returning 0 would skip any remaining methods for
1156 B<Note:> Looking at it another way, C<auto> actions have to return a
1157 true value to continue processing!
1159 =head4 URL Path Handling
1161 You can pass arguments as part of the URL path, separated with forward
1162 slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
1163 must be used. For example, suppose you want to handle
1164 C</foo/$bar/$baz>, where C<$bar> and C<$baz> may vary:
1166 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
1168 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
1170 sub boo : Path('foo/boo') { .. }
1171 sub hoo : Path('foo/boo/hoo') { .. }
1173 Catalyst matches actions in most specific to least specific order - that is, whatever matches the most pieces of the path wins:
1177 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
1179 So Catalyst would never mistakenly dispatch the first two URLs to the
1182 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
1183 still match a URL containing arguments; however the arguments won't be
1184 available via C<@_>, because the Regex will 'eat' them.
1186 Beware! If you write two matchers, that match the same path, with the
1187 same specificity (that is, they match the same quantity of the path),
1188 there's no guarantee which will actually get called. Non-regex
1189 matchers get tried first, followed by regex ones, but if you have, for
1192 package MyApp::Controller::Root;
1194 sub match1 :Path('/a/b') { }
1196 package MyApp::Controller::A;
1198 sub b :Local { } # Matches /a/b
1200 then Catalyst will call the one it finds first. In summary, Don't Do
1203 =head4 Query Parameter Processing
1205 Parameters passed in the URL query string are handled with methods in
1206 the L<Catalyst::Request> class. The C<param> method is functionally
1207 equivalent to the C<param> method of C<CGI.pm> and can be used in
1208 modules that require this.
1210 # http://localhost:3000/catalog/view/?category=hardware&page=3
1211 my $category = $c->req->param('category');
1212 my $current_page = $c->req->param('page') || 1;
1214 # multiple values for single parameter name
1215 my @values = $c->req->param('scrolling_list');
1217 # DFV requires a CGI.pm-like input hash
1218 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
1222 You control the application flow with the C<forward> method, which
1223 accepts the key of an action to execute. This can be an action in the
1224 same or another Catalyst controller, or a Class name, optionally
1225 followed by a method name. After a C<forward>, the control flow will
1226 return to the method from which the C<forward> was issued.
1228 A C<forward> is similar to a method call. The main differences are that
1229 it wraps the call in an C<eval> to allow exception handling; it
1230 automatically passes along the context object (C<$c> or C<$context>);
1231 and it allows profiling of each call (displayed in the log with
1234 sub hello : Global {
1235 my ( $self, $c ) = @_;
1236 $c->stash->{message} = 'Hello World!';
1237 $c->forward('check_message'); # $c is automatically included
1240 sub check_message : Private {
1241 my ( $self, $c ) = @_;
1242 return unless $c->stash->{message};
1243 $c->forward('show_message');
1246 sub show_message : Private {
1247 my ( $self, $c ) = @_;
1248 $c->res->body( $c->stash->{message} );
1251 A C<forward> does not create a new request, so your request object
1252 (C<$c-E<gt>req>) will remain unchanged. This is a key difference between
1253 using C<forward> and issuing a redirect.
1255 You can pass new arguments to a C<forward> by adding them
1256 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
1257 will be changed for the duration of the C<forward> only; upon
1258 return, the original value of C<$c-E<gt>req-E<gt>args> will
1261 sub hello : Global {
1262 my ( $self, $c ) = @_;
1263 $c->stash->{message} = 'Hello World!';
1264 $c->forward('check_message',[qw/test1/]);
1265 # now $c->req->args is back to what it was before
1268 sub check_message : Action {
1269 my ( $self, $c, $first_argument ) = @_;
1270 my $also_first_argument = $c->req->args->[0]; # now = 'test1'
1274 As you can see from these examples, you can just use the method name as
1275 long as you are referring to methods in the same controller. If you want
1276 to forward to a method in another controller, or the main application,
1277 you will have to refer to the method by absolute path.
1279 $c->forward('/my/controller/action');
1280 $c->forward('/default'); # calls default in main application
1282 You can also forward to classes and methods.
1284 sub hello : Global {
1285 my ( $self, $c ) = @_;
1286 $c->forward(qw/MyApp::View:Hello say_hello/);
1290 my ( $self, $c ) = @_;
1291 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
1294 package MyApp::View::Hello;
1297 my ( $self, $c ) = @_;
1298 $c->res->body('Hello World!');
1302 my ( $self, $c ) = @_;
1303 $c->res->body('Goodbye World!');
1306 This mechanism is used by L<Catalyst::Action::RenderView> to forward
1307 to the C<process> method in a view class.
1309 It should be noted that whilst forward is useful, it is not the only way
1310 of calling other code in Catalyst. Forward just gives you stats in the debug
1311 screen, wraps the code you're calling in an exception handler and localises
1312 C<< $c->request->args >>.
1314 If you don't want or need these features then it's perfectly acceptable
1315 (and faster) to do something like this:
1317 sub hello : Global {
1318 my ( $self, $c ) = @_;
1319 $c->stash->{message} = 'Hello World!';
1320 $self->check_message( $c, 'test1' );
1324 my ( $self, $c, $first_argument ) = @_;
1328 Note that C<forward> returns to the calling action and continues
1329 processing after the action finishes. If you want all further processing
1330 in the calling action to stop, use C<detach> instead, which will execute
1331 the C<detach>ed action and not return to the calling sub. In both cases,
1332 Catalyst will automatically try to call process() if you omit the
1337 Catalyst has a built-in http server for testing or local
1338 deployment. (Later, you can easily use a more powerful server, for
1339 example Apache/mod_perl or FastCGI, in a production environment.)
1341 Start your application on the command line...
1343 script/myapp_server.pl
1345 ...then visit http://localhost:3000/ in a browser to view the output.
1347 You can also do it all from the command line:
1349 script/myapp_test.pl http://localhost/
1351 Catalyst has a number of tools for actual regression testing of
1352 applications. The helper scripts will automatically generate basic tests
1353 that can be extended as you develop your project. To write your own
1354 comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
1357 For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
1365 =item * L<Catalyst::Manual::About>
1367 =item * L<Catalyst::Manual::Tutorial>
1377 Join #catalyst on irc.perl.org.
1378 Join #catalyst-dev on irc.perl.org to help with development.
1382 http://lists.scsys.co.uk/mailman/listinfo/catalyst
1383 http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev
1387 http://dev.catalystframework.org/wiki
1391 http://dev.catalystframework.org/wiki/faq
1395 Catalyst Contributors, see Catalyst.pm
1399 This library is free software. You can redistribute it and/or modify it under
1400 the same terms as Perl itself.