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 philosophy 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 better 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. This is the meat of where Catalyst works.
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).
127 Starting with Catalyst version 5.9 Catalyst ships with L<PSGI> integration
128 for even more powerful and flexible testing and deployment options. See
129 L<Catalyst::PSGI> for details.
135 The best part is that Catalyst implements all this flexibility in a very
140 =item * B<Building Block Interface>
142 Components interoperate very smoothly. For example, Catalyst
143 automatically makes a L</Context> object available to every
144 component. Via the context, you can access the request object, share
145 data between components, and control the flow of your
146 application. Building a Catalyst application feels a lot like snapping
147 together toy building blocks, and everything just works.
149 =item * B<Component Auto-Discovery>
151 No need to C<use> all of your components. Catalyst automatically finds
154 =item * B<Pre-Built Components for Popular Modules>
156 See L<Catalyst::Model::DBIC::Schema> for L<DBIx::Class>, or
157 L<Catalyst::View::TT> for L<Template Toolkit|Template>.
159 =item * B<Built-in Test Framework>
161 Catalyst comes with a built-in, lightweight http server and test
162 framework, making it easy to test applications from the web browser,
163 and the command line.
165 =item * B<Helper Scripts>
167 Catalyst provides helper scripts to quickly generate running starter
168 code for components and unit tests. Install L<Catalyst::Devel> and see
175 Here's how to install Catalyst and get a simple application up and
176 running, using the helper scripts described above.
180 Installation of Catalyst should be straightforward:
182 # perl -MCPAN -e 'install Catalyst::Runtime'
183 # perl -MCPAN -e 'install Catalyst::Devel'
184 # perl -MCPAN -e 'install Catalyst::View::TT'
191 $ script/myapp_create.pl controller Library::Login
193 =head4 Frank Speiser's Amazon EC2 Catalyst SDK
195 There are currently two flavors of publicly available Amazon Machine
196 Images (AMI) that include all the elements you'd need to begin
197 developing in a fully functional Catalyst environment within
199 L<Catalyst::Manual::Installation|Catalyst::Manual::Installation> for
205 $ script/myapp_server.pl
207 Now visit these locations with your favorite browser or user agent to see
210 (NOTE: Although we create a controller here, we don't actually use it.
211 Both of these URLs should take you to the welcome page.)
216 =item http://localhost:3000/
218 =item http://localhost:3000/library/login/
224 Let's see how Catalyst works, by taking a closer look at the components
225 and other parts of a Catalyst application.
229 Catalyst has an uncommonly flexible component system. You can define as
230 many L</Models>, L</Views>, and L</Controllers> as you like. As discussed
231 previously, the general idea is that the View is responsible for the
232 output of data to the user (typically via a web browser, but a View can
233 also generate PDFs or e-mails, for example); the Model is responsible
234 for providing data (typically from a relational database); and the
235 Controller is responsible for interacting with the user and deciding
236 how user input determines what actions the application takes.
238 In the world of MVC, there are frequent discussions and disagreements
239 about the nature of each element - whether certain types of logic
240 belong in the Model or the Controller, etc. Catalyst's flexibility
241 means that this decision is entirely up to you, the programmer;
242 Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
243 a general discussion of these issues.
245 Model, View and Controller components must inherit from L<Catalyst::Model>,
246 L<Catalyst::View> and L<Catalyst::Controller>, respectively. These, in turn, inherit
247 from L<Catalyst::Component> which provides a simple class structure and some
248 common class methods like C<config> and C<new> (constructor).
250 package MyApp::Controller::Catalog;
252 use namespace::autoclean;
254 BEGIN { extends 'Catalyst::Controller' }
256 __PACKAGE__->config( foo => 'bar' );
260 You don't have to C<use> or otherwise register Models, Views, and
261 Controllers. Catalyst automatically discovers and instantiates them
262 when you call C<setup> in the main application. All you need to do is
263 put them in directories named for each Component type. You can use a
264 short alias for each one.
268 =item * B<MyApp/Model/>
270 =item * B<MyApp/View/>
272 =item * B<MyApp/Controller/>
278 To show how to define views, we'll use an already-existing base class for the
279 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
280 inherit from this class:
282 package MyApp::View::TT;
285 use base 'Catalyst::View::TT';
289 (You can also generate this automatically by using the helper script:
291 script/myapp_create.pl view TT TT
293 where the first C<TT> tells the script that the name of the view should
294 be C<TT>, and the second that it should be a Template Toolkit view.)
296 This gives us a process() method and we can now just do
297 C<< $c->forward('MyApp::View::TT') >> to render our templates. The base class
298 makes process() implicit, so we don't have to say
299 C<< $c->forward(qw/MyApp::View::TT process/) >>.
302 my ( $self, $c ) = @_;
303 $c->stash->{template} = 'hello.tt';
307 my ( $self, $c ) = @_;
308 $c->forward( $c->view('TT') );
311 You normally render templates at the end of a request, so it's a perfect
312 use for the global C<end> action.
314 In practice, however, you would use a default C<end> action as supplied
315 by L<Catalyst::Action::RenderView>.
317 Also, be sure to put the template under the directory specified in
318 C<< $c->config->{root} >>, or you'll end up looking at the debug
323 Models are providers of data. This data could come from anywhere - a
324 search engine index, a spreadsheet, the file system - but typically a
325 Model represents a database table. The data source does not
326 intrinsically have much to do with web applications or Catalyst - it
327 could just as easily be used to write an offline report generator or a
330 To show how to define models, again we'll use an already-existing base
331 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
332 We'll also need L<DBIx::Class::Schema::Loader>.
334 But first, we need a database.
338 id INTEGER PRIMARY KEY,
343 id INTEGER PRIMARY KEY,
344 foo INTEGER REFERENCES foo,
348 INSERT INTO foo (data) VALUES ('TEST!');
350 % sqlite3 /tmp/myapp.db < myapp.sql
352 Now we can create a DBIC::Schema model for this database.
354 script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
356 L<DBIx::Class::Schema::Loader> can automatically load table layouts and
357 relationships, and convert them into a static schema definition
358 C<MySchema>, which you can edit later.
360 Use the stash to pass data to your templates.
362 We add the following to MyApp/Controller/Root.pm
365 my ( $self, $c, $id ) = @_;
367 $c->stash->{item} = $c->model('MyModel::Foo')->find($id);
373 my ( $self, $c ) = @_;
375 $c->stash->{template} ||= 'index.tt';
376 $c->forward( $c->view('TT') );
379 We then create a new template file "root/index.tt" containing:
381 The Id's data is [% item.data %]
383 Models do not have to be part of your Catalyst application; you
384 can always call an outside module that serves as your Model:
388 my ( $self, $c ) = @_;
390 $c->stash->{template} = 'list.tt';
392 use Some::Outside::Database::Module;
393 my @records = Some::Outside::Database::Module->search({
394 artist => 'Led Zeppelin',
397 $c->stash->{records} = \@records;
400 But by using a Model that is part of your Catalyst application, you
401 gain several things: you don't have to C<use> each component, Catalyst
402 will find and load it automatically at compile-time; you can
403 C<forward> to the module, which can only be done to Catalyst
404 components. Only Catalyst components can be fetched with
405 C<< $c->model('SomeModel') >>.
407 Happily, since many people have existing Model classes that they
408 would like to use with Catalyst (or, conversely, they want to
409 write Catalyst models that can be used outside of Catalyst, e.g.
410 in a cron job), it's trivial to write a simple component in
411 Catalyst that slurps in an outside Model:
413 package MyApp::Model::DB;
414 use base qw/Catalyst::Model::DBIC::Schema/;
416 schema_class => 'Some::DBIC::Schema',
417 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
421 and that's it! Now C<Some::DBIC::Schema> is part of your
422 Cat app as C<MyApp::Model::DB>.
424 Within Catalyst, the common approach to writing a model for your
425 application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
426 bunch of XMLs, or anything really) with an object that contains
427 configuration data, convenience methods, and so forth. Thus you
428 will in effect have two models - a wrapper model that knows something
429 about Catalyst and your web application, and a generic model that is
430 totally independent of these needs.
432 Technically, within Catalyst a model is a B<component> - an instance of
433 the model's class belonging to the application. It is important to
434 stress that the lifetime of these objects is per application, not per
437 While the model base class (L<Catalyst::Model>) provides things like
438 C<config> to better integrate the model into the application, sometimes
439 this is not enough, and the model requires access to C<$c> itself.
441 Situations where this need might arise include:
447 Interacting with another model
451 Using per-request data to control behavior
455 Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
459 From a style perspective it's usually considered bad form to make your
460 model "too smart" about things - it should worry about business logic
461 and leave the integration details to the controllers. If, however, you
462 find that it does not make sense at all to use an auxiliary controller
463 around the model, and the model's need to access C<$c> cannot be
464 sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
468 Multiple controllers are a good way to separate logical domains of your
471 package MyApp::Controller::Login;
473 use base qw/Catalyst::Controller/;
475 sub sign_in : Path("sign-in") { }
476 sub new_password : Path("new-password") { }
477 sub sign_out : Path("sign-out") { }
479 package MyApp::Controller::Catalog;
481 use base qw/Catalyst::Controller/;
486 package MyApp::Controller::Cart;
488 use base qw/Catalyst::Controller/;
491 sub update : Local { }
492 sub order : Local { }
494 Note that you can also supply attributes via the Controller's config so
495 long as you have at least one attribute on a subref to be exported
496 (:Action is commonly used for this) - for example the following is
497 equivalent to the same controller above:
499 package MyApp::Controller::Login;
501 use base qw/Catalyst::Controller/;
505 'sign_in' => { Path => 'sign-in' },
506 'new_password' => { Path => 'new-password' },
507 'sign_out' => { Path => 'sign-out' },
511 sub sign_in : Action { }
512 sub new_password : Action { }
513 sub sign_out : Action { }
515 =head3 ACCEPT_CONTEXT
517 Whenever you call C<< $c->component("Foo") >> you get back an object - the
518 instance of the model. If the component supports the C<ACCEPT_CONTEXT>
519 method instead of returning the model itself, the return value of C<<
520 $model->ACCEPT_CONTEXT( $c ) >> will be used.
522 This means that whenever your model/view/controller needs to talk to
523 C<$c> it gets a chance to do this when it's needed.
525 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
526 with the context object set, or it will return a thin wrapper that contains
527 C<$c> and delegates to the per-application model object.
529 Generally it's a bad idea to expose the context object (C<$c>) in your
530 model or view code. Instead you use the C<ACCEPT_CONTEXT> subroutine
531 to grab the bits of the context object that you need, and provide
532 accessors to them in the model. This ensures that C<$c> is only in
533 scope where it is needed which reduces maintenance and debugging
534 headaches. So, if for example you needed two
535 L<Catalyst::Model::DBIC::Schema> models in the same Catalyst model
536 code, you might do something like this:
538 __PACKAGE__->mk_accessors(qw(model1_schema model2_schema));
540 my ( $self, $c, @extra_arguments ) = @_;
541 $self = bless({ %$self,
542 model1_schema => $c->model('Model1')->schema,
543 model2_schema => $c->model('Model2')->schema
548 This effectively treats $self as a B<prototype object> that gets a new
549 parameter. C<@extra_arguments> comes from any trailing arguments to
550 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...)
551 >>, C<< $c->view(...) >> etc).
553 In a subroutine in the model code, we can then do this:
557 my $schema1 = $self->model1_schema;
558 my $schema2 = $self->model2_schema;
562 Note that we still want the Catalyst models to be a thin wrapper
563 around classes that will work independently of the Catalyst
564 application to promote reusability of code. Here we might just want
565 to grab the C<< $c->model('DB')->schema >> so as to get the connection
566 information from the Catalyst application's configuration for example.
568 The life time of this value is B<per usage>, and not per request. To
569 make this per request you can use the following technique:
571 Add a field to C<$c>, like C<my_model_instance>. Then write your
572 C<ACCEPT_CONTEXT> method to look like this:
575 my ( $self, $c ) = @_;
577 if ( my $per_request = $c->my_model_instance ) {
580 my $new_instance = bless { %$self, c => $c }, ref($self);
581 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
582 $c->my_model_instance( $new_instance );
583 return $new_instance;
587 For a similar technique to grab a new component instance on each
588 request, see L<Catalyst::Component::InstancePerContext>.
590 =head3 Application Class
592 In addition to the Model, View, and Controller components, there's a
593 single class that represents your application itself. This is where you
594 configure your application, load plugins, and extend Catalyst.
599 use parent qw/Catalyst/;
600 use Catalyst qw/-Debug ConfigLoader Static::Simple/;
602 name => 'My Application',
604 # You can put anything else you want in here:
605 my_configuration_variable => 'something',
609 In older versions of Catalyst, the application class was where you put
610 global actions. However, as of version 5.66, the recommended practice is
611 to place such actions in a special Root controller (see L</Actions>,
612 below), to avoid namespace collisions.
618 The name of your application.
622 Optionally, you can specify a B<root> parameter for templates and static
623 data. If omitted, Catalyst will try to auto-detect the directory's
624 location. You can define as many parameters as you want for plugins or
625 whatever you need. You can access them anywhere in your application via
626 C<< $context->config->{$param_name} >>.
630 Catalyst automatically blesses a Context object into your application
631 class and makes it available everywhere in your application. Use the
632 Context to directly interact with Catalyst and glue your L</Components>
633 together. For example, if you need to use the Context from within a
634 Template Toolkit template, it's already there:
636 <h1>Welcome to [% c.config.name %]!</h1>
638 As illustrated in our URL-to-Action dispatching example, the Context is
639 always the second method parameter, behind the Component object
640 reference or class name itself. Previously we called it C<$context> for
641 clarity, but most Catalyst developers just call it C<$c>:
644 my ( $self, $c ) = @_;
645 $c->res->body('Hello World!');
648 The Context contains several important objects:
652 =item * L<Catalyst::Request>
657 The request object contains all kinds of request-specific information, like
658 query parameters, cookies, uploads, headers, and more.
660 $c->req->params->{foo};
661 $c->req->cookies->{sessionid};
662 $c->req->headers->content_type;
664 $c->req->uri_with( { page = $pager->next_page } );
666 =item * L<Catalyst::Response>
671 The response is like the request, but contains just response-specific
674 $c->res->body('Hello World');
675 $c->res->status(404);
676 $c->res->redirect('http://oook.de');
684 =item * L<Catalyst::Log>
687 $c->log->debug('Something happened');
688 $c->log->info('Something you should know');
693 $c->stash->{foo} = 'bar';
694 $c->stash->{baz} = {baz => 'qox'};
695 $c->stash->{fred} = [qw/wilma pebbles/];
701 The last of these, the stash, is a universal hash for sharing data among
702 application components. For an example, we return to our 'hello' action:
705 my ( $self, $c ) = @_;
706 $c->stash->{message} = 'Hello World!';
707 $c->forward('show_message');
710 sub show_message : Private {
711 my ( $self, $c ) = @_;
712 $c->res->body( $c->stash->{message} );
715 Note that the stash should be used only for passing data in an
716 individual request cycle; it gets cleared at a new request. If you need
717 to maintain persistent data, use a session. See
718 L<Catalyst::Plugin::Session> for a comprehensive set of
719 Catalyst-friendly session-handling tools.
723 You've already seen some examples of actions in this document:
724 subroutines with C<:Path> and C<:Local> attributes attached.
725 Here, we explain what actions are and how these attributes affect
728 When Catalyst processes a webpage request, it looks for actions to
729 take that will deal with the incoming request and produce a response
730 such as a webpage. You create these actions for your application by
731 writing subroutines within your controller and marking them with
732 special attributes. The attributes, the namespace, and the function
733 name determine when Catalyst will call the subroutine.
735 These action subroutines call certain functions to say what response
736 the webserver will give to the web request. They can also tell
737 Catalyst to run other actions on the request (one example of this is
738 called forwarding the request; this is discussed later).
740 Action subroutines must have a special attribute on to show that they
741 are actions - as well as marking when to call them, this shows that
742 they take a specific set of arguments and behave in a specific way.
743 At startup, Catalyst looks for all the actions in controllers,
744 registers them and creates L<Catalyst::Action> objects describing
745 them. When requests come in, Catalyst chooses which actions should be
746 called to handle the request.
748 (Occasionally, you might use the action objects directly, but in
749 general, when we talk about actions, we're talking about the
750 subroutines in your application that do things to process a request.)
752 You can choose one of several attributes for action subroutines; these
753 specify which requests are processed by that subroutine. Catalyst
754 will look at the URL it is processing, and the actions that it has
755 found, and automatically call the actions it finds that match the
756 circumstances of the request.
758 The URL (for example C<http://localhost:3000/foo/bar>) consists of two
759 parts, the base, describing how to connect to the server
760 (C<http://localhost:3000/> in this example) and the path, which the
761 server uses to decide what to return (C<foo/bar>). Please note that the
762 trailing slash after the hostname[:port] always belongs to base and
763 not to the path. Catalyst uses only the path part when trying to find
766 Depending on the type of action used, the URLs may match a combination
767 of the controller namespace, the arguments passed to the action
768 attribute, and the name of the subroutine.
772 =item * B<Controller namespaces>
774 The namespace is a modified form of the component's class (package)
775 name. This modified class name excludes the parts that have a
776 pre-defined meaning in Catalyst ("MyApp::Controller" in the above
777 example), replaces "::" with "/", and converts the name to lower case.
778 See L</Components> for a full explanation of the pre-defined meaning
779 of Catalyst component class names.
781 =item * B<Overriding the namespace>
783 Note that C<< __PACKAGE__->config->(namespace => ... ) >> can be used to override the
784 current namespace when matching. So:
786 package MyApp::Controller::Example;
788 would normally use 'example' as its namespace for matching, but if
789 this is specially overridden with
791 __PACKAGE__->config( namespace => 'thing' );
793 it matches using the namespace 'thing' instead.
795 =item * B<Application-Wide Actions>
797 MyApp::Controller::Root, as created by the catalyst.pl script, will
798 typically contain actions which are called for the top level of the
799 application (e.g. C<http://localhost:3000/>):
801 package MyApp::Controller::Root;
802 use base 'Catalyst::Controller';
804 # Sets the actions in this controller to be registered with no prefix
805 # so they function identically to actions created in MyApp.pm
807 __PACKAGE__->config( namespace => '');
810 my ( $self, $context ) = @_;
811 $context->response->status(404);
812 $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, such
824 as :Path and :Local match at the start of the URL path (i.e. 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> C<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;
857 $c->res->body('sub bar in Controller::Foo triggered on a request for '
863 Matches C<http://localhost:3000/bar> - that is, the action is mapped
864 directly to the method name, ignoring the controller namespace.
866 C<:Global> always matches from the application root: it is simply
867 shorthand for C<:Path('/methodname')>. C<:Local> is shorthand for
868 C<:Path('methodname')>, which takes the controller namespace as described
871 Usage of the C<Global> handler is rare in all but very old Catalyst
872 applications (e.g. before Catalyst 5.7). The use cases where C<Global>
873 used to make sense are now largely replaced by the C<Chained> dispatch
874 type, or by empty C<Path> declarations on an controller action. C<Global>
875 is still included in Catalyst for backwards compatibility, although
876 legitimate use-cases for it may still exist.
878 =item * Changing handler behaviour: eating arguments (C<:Args>)
880 C<:Args> is not an action type per se, but an action modifier - it adds a
881 match restriction to any action it's provided to, additionally
882 requiring as many path parts as are specified for the action to be
883 matched. For example, in MyApp::Controller::Foo,
887 would match any URL starting /foo/bar. To restrict this you can do
889 sub bar :Local :Args(1)
891 to only match URLs starting /foo/bar/* - with one additional path
892 element required after 'bar'.
894 NOTE that adding C<:Args(0)> and omitting C<:Args> are B<not>
897 C<:Args(0)> means that no arguments are taken. Thus, the URL and path must
900 No C<:Args> at all means that B<any number> of arguments are taken. Thus, any
901 URL that B<starts with> the controller's path will match. Obviously, this means
902 you cannot chain from an action that does not specify args, as the next action
903 in the chain will be swallowed as an arg to the first!
906 =item * Literal match (C<:Path>)
908 C<Path> actions match things starting with a precise specified path,
911 C<Path> actions without a leading forward slash match a specified path
912 relative to their current namespace. This example matches URLs
913 starting with C<http://localhost:3000/my/controller/foo/bar>:
915 package MyApp::Controller::My::Controller;
916 sub bar : Path('foo/bar') { }
918 C<Path> actions B<with> a leading slash ignore their namespace, and
919 match from the start of the URL path. Example:
921 package MyApp::Controller::My::Controller;
922 sub bar : Path('/foo/bar') { }
924 This matches URLs beginning with C<http://localhost:3000/foo/bar>.
926 Empty C<Path> definitions match on the namespace only, exactly like
929 package MyApp::Controller::My::Controller;
932 The above code matches C<http://localhost:3000/my/controller>.
934 Actions with the C<:Local> attribute are similarly equivalent to
935 C<:Path('action_name')>:
941 sub foo : Path('foo') { }
943 =item * Pattern match (C<:Regex> and C<:LocalRegex>)
945 B<Status: deprecated.> Use Chained methods or other techniques.
946 If you really depend on this, install the standalone
947 L<Catalyst::DispatchType::Regex> distribution.
949 package MyApp::Controller::My::Controller;
950 sub bar : Regex('^item(\d+)/order(\d+)$') { }
952 This matches any URL that matches the pattern in the action key, e.g.
953 C<http://localhost:3000/item23/order42>. The '' around the regexp is
954 optional, but perltidy likes it. :)
956 C<:Regex> matches act globally, i.e. without reference to the namespace
957 from which they are called. So the above will B<not> match
958 C<http://localhost:3000/my/controller/item23/order42> - use a
959 C<:LocalRegex> action instead.
961 package MyApp::Controller::My::Controller;
962 sub bar : LocalRegex('^widget(\d+)$') { }
964 C<:LocalRegex> actions act locally, i.e. the namespace is matched
965 first. The above example would match urls like
966 C<http://localhost:3000/my/controller/widget23>.
968 If you omit the "C<^>" from either sort of regex, then it will match any depth
971 package MyApp::Controller::Catalog;
972 sub bar : LocalRegex('widget(\d+)$') { }
974 This differs from the previous example in that it will match
975 C<http://localhost:3000/my/controller/foo/widget23> - and a number of
978 For both C<:LocalRegex> and C<:Regex> actions, if you use capturing
979 parentheses to extract values within the matching URL, those values
980 are available in the C<< $c->req->captures >> array. In the above
981 example, "widget23" would capture "23" in the above example, and
982 C<< $c->req->captures->[0] >> would be "23". If you want to
983 pass arguments at the end of your URL, you must use regex action
984 keys. See L</URL Path Handling> below.
986 =item * Chained handlers (C<:Chained>)
988 Catalyst also provides a method to build and dispatch chains of actions,
991 sub catalog : Chained : CaptureArgs(1) {
992 my ( $self, $c, $arg ) = @_;
996 sub item : Chained('catalog') : Args(1) {
997 my ( $self, $c, $arg ) = @_;
1001 to handle a C</catalog/*/item/*> path. Matching actions are called
1002 one after another - C<catalog()> gets called and handed one path
1003 element, then C<item()> gets called with another one. For further
1004 information about this dispatch type, please see
1005 L<Catalyst::DispatchType::Chained>.
1009 sub foo : Private { }
1011 This will never match a URL - it provides a private action which can
1012 be called programmatically from within Catalyst, but is never called
1013 automatically due to the URL being requested.
1015 Catalyst's C<:Private> attribute is exclusive and doesn't work with other
1016 attributes (so will not work combined with C<:Path> or C<:Chained>
1017 attributes, for instance).
1019 Private actions can only be executed explicitly from inside a Catalyst
1020 application. You might do this in your controllers by calling
1021 catalyst methods such as C<forward> or C<detach> to fire them:
1027 See L</Flow Control> for a full explanation of how you can pass
1028 requests on to other actions. Note that, as discussed there, when
1029 forwarding from another component, you must use the absolute path to
1030 the method, so that a private C<bar> method in your
1031 C<MyApp::Controller::Catalog::Order::Process> controller must, if
1032 called from elsewhere, be reached with
1033 C<< $c->forward('/catalog/order/process/bar') >>.
1037 B<Note:> After seeing these examples, you probably wonder what the
1038 point is of defining subroutine names for regex and path
1039 actions. However, every public action is also a private one with a
1040 path corresponding to its namespace and subroutine name, so you have
1041 one unified way of addressing components in your C<forward>s.
1043 =head4 Built-in special actions
1045 If present, the special actions C< index >, C< auto >, C<begin>,
1046 C<end> and C< default > are called at certain points in the request
1049 In response to specific application states, Catalyst will automatically
1050 call these built-in actions in your application class:
1054 =item * B<default : Path>
1056 This is called when no other action matches. It could be used, for
1057 example, for displaying a generic frontpage for the main app, or an
1058 error page for individual controllers. B<Note>: in older Catalyst
1059 applications you will see C<default : Private> which is roughly
1060 speaking equivalent.
1063 =item * B<index : Path : Args (0) >
1065 C<index> is much like C<default> except that it takes no arguments and
1066 it is weighted slightly higher in the matching process. It is useful
1067 as a static entry point to a controller, e.g. to have a static welcome
1068 page. Note that it's also weighted higher than Path. Actually the sub
1069 name C<index> can be called anything you want. The sub attributes are
1070 what determines the behaviour of the action. B<Note>: in older
1071 Catalyst applications, you will see C<index : Private> used, which is
1072 roughly speaking equivalent.
1074 =item * B<begin : Private>
1076 Called at the beginning of a request, once the controller that will
1077 run has been identified, but before any URL-matching actions are
1078 called. Catalyst will call the C<begin> function in the controller
1079 which contains the action matching the URL.
1081 =item * B<end : Private>
1083 Called at the end of a request, after all URL-matching actions are called.
1084 Catalyst will call the C<end> function in the controller
1085 which contains the action matching the URL.
1087 =item * B<auto : Private>
1089 In addition to the normal built-in actions, you have a special action
1090 for making chains, C<auto>. C<auto> actions will be run after any
1091 C<begin>, but before your URL-matching action is processed. Unlike the other
1092 built-ins, multiple C<auto> actions can be called; they will be
1093 called in turn, starting with the application class and going through
1094 to the most specific class.
1098 =head4 Built-in actions in controllers/autochaining
1100 package MyApp::Controller::Foo;
1101 sub begin : Private { }
1102 sub default : Path { }
1105 You can define built-in actions within your controllers as well as on
1106 your application class. In other words, for each of the three built-in
1107 actions above, only one will be run in any request cycle. Thus, if
1108 C<MyApp::Controller::Catalog::begin> exists, it will be run in place
1109 of C<MyApp::begin> if you're in the C<catalog> namespace, and
1110 C<MyApp::Controller::Catalog::Order::begin> would override this in
1113 sub auto : Private { }
1115 C<auto>, however, doesn't override like this: providing they exist,
1116 C<MyApp::Controller::Root::auto>, C<MyApp::Controller::Catalog::auto> and
1117 C<MyApp::Catalog::Order::auto> would be called in turn.
1119 Here are some examples of the order in which the various built-ins
1124 =item for a request for C</foo/foo>
1126 MyApp::Controller::Foo::auto
1127 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
1128 MyApp::Controller::Foo::end
1130 =item for a request for C</foo/bar/foo>
1132 MyApp::Controller::Foo::Bar::begin
1133 MyApp::Controller::Foo::auto
1134 MyApp::Controller::Foo::Bar::auto
1135 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
1136 MyApp::Controller::Foo::Bar::end
1140 The C<auto> action is also distinguished by the fact that you can break
1141 out of the processing chain by returning 0. If an C<auto> action returns
1142 0, any remaining actions will be skipped, except for C<end>. So, for the
1143 request above, if the first auto returns false, the chain would look
1148 =item for a request for C</foo/bar/foo> where first C<auto> returns
1151 MyApp::Controller::Foo::Bar::begin
1152 MyApp::Controller::Foo::auto # returns false, skips some calls:
1153 # MyApp::Controller::Foo::Bar::auto - never called
1154 # MyApp::Controller::Foo::Bar::foo - never called
1155 MyApp::Controller::Foo::Bar::end
1157 You can also C<die> in the auto action; in that case, the request will
1158 go straight to the finalize stage, without processing further
1159 actions. So in the above example, C<MyApp::Controller::Foo::Bar::end>
1164 An example of why one might use C<auto> is an authentication action:
1165 you could set up a C<auto> action to handle authentication in your
1166 application class (which will always be called first), and if
1167 authentication fails, returning 0 would skip any remaining methods for
1170 B<Note:> Looking at it another way, C<auto> actions have to return a
1171 true value to continue processing!
1173 =head4 URL Path Handling
1175 You can pass arguments as part of the URL path, separated with forward
1176 slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
1177 must be used. For example, suppose you want to handle
1178 C</foo/$bar/$baz>, where C<$bar> and C<$baz> may vary:
1180 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
1182 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
1184 sub boo : Path('foo/boo') { .. }
1185 sub hoo : Path('foo/boo/hoo') { .. }
1187 Catalyst matches actions in most specific to least specific order - that is, whatever matches the most pieces of the path wins:
1191 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
1193 So Catalyst would never mistakenly dispatch the first two URLs to the
1196 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
1197 still match a URL containing arguments; however the arguments won't be
1198 available via C<@_>, because the Regex will 'eat' them.
1200 Beware! If you write two matchers, that match the same path, with the
1201 same specificity (that is, they match the same quantity of the path),
1202 there's no guarantee which will actually get called. Non-regex
1203 matchers get tried first, followed by regex ones, but if you have, for
1206 package MyApp::Controller::Root;
1208 sub match1 :Path('/a/b') { }
1210 package MyApp::Controller::A;
1212 sub b :Local { } # Matches /a/b
1214 then Catalyst will call the one it finds first. In summary, Don't Do
1217 =head4 Query Parameter Processing
1219 Parameters passed in the URL query string are handled with methods in
1220 the L<Catalyst::Request> class. The C<param> method is functionally
1221 equivalent to the C<param> method of L<CGI.pm|CGI> and can be used in
1222 modules that require this.
1224 # http://localhost:3000/catalog/view/?category=hardware&page=3
1225 my $category = $c->req->param('category');
1226 my $current_page = $c->req->param('page') || 1;
1228 # multiple values for single parameter name
1229 my @values = $c->req->param('scrolling_list');
1231 # DFV requires a CGI.pm-like input hash
1232 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
1236 You control the application flow with the C<forward> method, which
1237 accepts the key of an action to execute. This can be an action in the
1238 same or another Catalyst controller, or a Class name, optionally
1239 followed by a method name. After a C<forward>, the control flow will
1240 return to the method from which the C<forward> was issued.
1242 A C<forward> is similar to a method call. The main differences are that
1243 it wraps the call in an C<eval> to allow exception handling; it
1244 automatically passes along the context object (C<$c> or C<$context>);
1245 and it allows profiling of each call (displayed in the log with
1248 sub hello : Global {
1249 my ( $self, $c ) = @_;
1250 $c->stash->{message} = 'Hello World!';
1251 $c->forward('check_message'); # $c is automatically included
1254 sub check_message : Private {
1255 my ( $self, $c ) = @_;
1256 return unless $c->stash->{message};
1257 $c->forward('show_message');
1260 sub show_message : Private {
1261 my ( $self, $c ) = @_;
1262 $c->res->body( $c->stash->{message} );
1265 A C<forward> does not create a new request, so your request object
1266 (C<< $c->req >>) will remain unchanged. This is a key difference between
1267 using C<forward> and issuing a redirect.
1269 You can pass new arguments to a C<forward> by adding them
1270 in an anonymous array. In this case C<< $c->req->args >>
1271 will be changed for the duration of the C<forward> only; upon
1272 return, the original value of C<< $c->req->args >> will
1275 sub hello : Global {
1276 my ( $self, $c ) = @_;
1277 $c->stash->{message} = 'Hello World!';
1278 $c->forward('check_message',[qw/test1/]);
1279 # now $c->req->args is back to what it was before
1282 sub check_message : Action {
1283 my ( $self, $c, $first_argument ) = @_;
1284 my $also_first_argument = $c->req->args->[0]; # now = 'test1'
1288 As you can see from these examples, you can just use the method name as
1289 long as you are referring to methods in the same controller. If you want
1290 to forward to a method in another controller, or the main application,
1291 you will have to refer to the method by absolute path.
1293 $c->forward('/my/controller/action');
1294 $c->forward('/default'); # calls default in main application
1296 You can also forward to classes and methods.
1298 sub hello : Global {
1299 my ( $self, $c ) = @_;
1300 $c->forward(qw/MyApp::View:Hello say_hello/);
1304 my ( $self, $c ) = @_;
1305 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
1308 package MyApp::View::Hello;
1311 my ( $self, $c ) = @_;
1312 $c->res->body('Hello World!');
1316 my ( $self, $c ) = @_;
1317 $c->res->body('Goodbye World!');
1320 This mechanism is used by L<Catalyst::Action::RenderView> to forward
1321 to the C<process> method in a view class.
1323 It should be noted that whilst forward is useful, it is not the only way
1324 of calling other code in Catalyst. Forward just gives you stats in the debug
1325 screen, wraps the code you're calling in an exception handler and localises
1326 C<< $c->request->args >>.
1328 If you don't want or need these features then it's perfectly acceptable
1329 (and faster) to do something like this:
1331 sub hello : Global {
1332 my ( $self, $c ) = @_;
1333 $c->stash->{message} = 'Hello World!';
1334 $self->check_message( $c, 'test1' );
1338 my ( $self, $c, $first_argument ) = @_;
1342 Note that C<forward> returns to the calling action and continues
1343 processing after the action finishes. If you want all further processing
1344 in the calling action to stop, use C<detach> instead, which will execute
1345 the C<detach>ed action and not return to the calling sub. In both cases,
1346 Catalyst will automatically try to call process() if you omit the
1351 Catalyst has a built-in http server for testing or local
1352 deployment. (Later, you can easily use a more powerful server, for
1353 example Apache/mod_perl or FastCGI, in a production environment.)
1355 Start your application on the command line...
1357 script/myapp_server.pl
1359 ...then visit http://localhost:3000/ in a browser to view the output.
1361 You can also do it all from the command line:
1363 script/myapp_test.pl http://localhost/
1365 Catalyst has a number of tools for actual regression testing of
1366 applications. The helper scripts will automatically generate basic tests
1367 that can be extended as you develop your project. To write your own
1368 comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
1371 For more testing ideas, see L<Catalyst::Manual::Tutorial::08_Testing>.
1379 =item * L<Catalyst::Manual::About>
1381 =item * L<Catalyst::Manual::Tutorial>
1391 Join #catalyst on irc.perl.org.
1392 Join #catalyst-dev on irc.perl.org to help with development.
1396 http://lists.scsys.co.uk/mailman/listinfo/catalyst
1397 http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev
1401 http://dev.catalystframework.org/wiki
1405 http://dev.catalystframework.org/wiki/faq
1409 Catalyst Contributors, see Catalyst.pm
1413 This library is free software. You can redistribute it and/or modify it under
1414 the same terms as Perl itself.