3 Catalyst::Manual::Cookbook - Cooking with Catalyst
7 Yummy code like your mum used to bake!
11 =head2 Force debug screen
13 You can force Catalyst to display the debug screen at the end of the
14 request by placing a C<die()> call in the C<end> action.
17 my ( $self, $c ) = @_;
21 If you're tired of removing and adding this all the time, you
22 can add a condition in the C<end> action:
25 my ( $self, $c ) = @_;
26 die "forced debug" if $c->req->params->{dump_info};
29 Then just add to your query string C<"&dump_info=1">, or the like,
30 to force debug output.
32 =head2 Disable statistics
34 Just add this line to your application class if you don't want those nifty
35 statistics in your debug messages.
37 sub Catalyst::Log::info { }
41 Scaffolding is very simple with Catalyst.
42 Just use Catalyst::Model::CDBI::CRUD as your base class.
44 # lib/MyApp/Model/CDBI.pm
45 package MyApp::Model::CDBI;
48 use base 'Catalyst::Model::CDBI::CRUD';
51 dsn => 'dbi:SQLite:/tmp/myapp.db',
60 use Catalyst 'FormValidator';
63 name => 'My Application',
64 root => '/home/joeuser/myapp/root'
67 sub my_table : Global {
68 my ( $self, $c ) = @_;
69 $c->form( optional => [ MyApp::Model::CDBI::Table->columns ] );
70 $c->forward('MyApp::Model::CDBI::Table');
75 Modify the $c->form() parameters to match your needs, and don't forget
76 to copy the templates into the template root. Can't find the templates?
77 They were in the CRUD model distribution, so you can do B<look
78 Catalyst::Model::CDBI::CRUD> from the CPAN shell to find them.
80 Other Scaffolding modules are in development at the time of writing.
82 =head2 Single file upload with Catalyst
84 To implement uploads in Catalyst you need to have a HTML form similiar to
87 <form action="/upload" method="post" enctype="multipart/form-data">
88 <input type="hidden" name="form_submit" value="yes">
89 <input type="file" name="my_file">
90 <input type="submit" value="Send">
93 It's very important not to forget C<enctype="multipart/form-data"> in
96 Catalyst Controller module 'upload' action:
101 if ( $c->request->parameters->{form_submit} eq 'yes' ) {
103 if ( my $upload = $c->request->upload('my_file') ) {
105 my $filename = $upload->filename;
106 my $target = "/tmp/upload/$filename";
108 unless ( $upload->link_to($target) || $upload->copy_to($target) ) {
109 die( "Failed to copy '$filename' to '$target': $!" );
114 $c->stash->{template} = 'file_upload.html';
117 =head2 Multiple file upload with Catalyst
119 Code for uploading multiple files from one form needs a few changes:
121 The form should have this basic structure:
123 <form action="/upload" method="post" enctype="multipart/form-data">
124 <input type="hidden" name="form_submit" value="yes">
125 <input type="file" name="file1" size="50"><br>
126 <input type="file" name="file2" size="50"><br>
127 <input type="file" name="file3" size="50"><br>
128 <input type="submit" value="Send">
131 And in the Controller:
136 if ( $c->request->parameters->{form_submit} eq 'yes' ) {
138 for my $field ( $c->req->upload ) {
140 my $upload = $c->req->upload($field);
141 my $filename = $upload->filename;
142 my $target = "/tmp/upload/$filename";
144 unless ( $upload->link_to($target) || $upload->copy_to($target) ) {
145 die( "Failed to copy '$filename' to '$target': $!" );
150 $c->stash->{template} = 'file_upload.html';
153 C<for my $field ($c-E<gt>req->upload)> loops automatically over all file
154 input fields and gets input names. After that is basic file saving code,
155 just like in single file upload.
157 Notice: C<die>ing might not be what you want to do, when an error
158 occurs, but it works as an example. A better idea would be to store
159 error C<$!> in $c->stash->{error} and show a custom error template
160 displaying this message.
162 For more information about uploads and usable methods look at
163 L<Catalyst::Request::Upload> and L<Catalyst::Request>.
165 =head2 Authentication with Catalyst::Plugin::Authentication::CDBI
167 There are (at least) two ways to implement authentication with this plugin:
168 1) only checking username and password
169 2) checking username, password, and the roles the user has
171 For both variants you'll need the following code in your MyApp package:
173 use Catalyst qw/Session::FastMmap Static Authentication::CDBI/;
175 MyApp->config( authentication => { user_class => 'MyApp::M::MyApp::Users',
176 user_field => 'email',
177 password_field => 'password' });
179 'user_class' is a Class::DBI class for your users table.
180 'user_field' tells which field is used for username lookup (might be
181 email, first name, surname etc.).
182 'password_field' is, well, password field in your table and by default
183 password is stored in plain text. Authentication::CDBI looks for 'user'
184 and 'password' fields in table, if they're not defined in the config.
186 In PostgreSQL, the users table might be something like:
191 surname varchar(100),
192 password varchar(100),
197 We'll discuss the first variant for now:
198 1. user:password login/auth without roles
200 To log in a user you might use an action like this:
204 if ($c->req->params->{username}) {
205 $c->session_login($c->req->params->{username},
206 $c->req->params->{password} );
207 if ($c->req->{user}) {
208 $c->forward('?restricted_area');
213 This action should not go in your MyApp class...if it does, it will
214 conflict with the built-in method of the same name. Instead, put it
215 in a Controller class.
217 $c->req->params->{username} and $c->req->params->{password} are html
218 form parameters from a login form. If login succeeds, then
219 $c->req->{user} contains the username of the authenticated user.
221 If you want to remember the user's login status in between further
222 requests, then just use the C<$c-E<gt>session_login> method. Catalyst will
223 create a session id and session cookie and automatically append session
224 id to all urls. So all you have to do is just check $c->req->{user}
227 To log out a user, just call $c->session_logout.
229 Now let's take a look at the second variant:
230 2. user:password login/auth with roles
232 To use roles you need to add the following parameters to MyApp->config in the 'authentication' section:
234 role_class => 'MyApp::M::MyApp::Roles',
235 user_role_class => 'MyApp::M::MyApp::UserRoles',
236 user_role_user_field => 'user_id',
237 user_role_role_field => 'role_id',
239 Corresponding tables in PostgreSQL could look like this:
247 CREATE TABLE user_roles (
251 primary key(user_role_id),
252 foreign key(user_id) references users(user_id),
253 foreign key(role_id) references roles(role_id)
256 The 'roles' table is a list of role names and the 'user_role' table is
257 used for the user -> role lookup.
259 Now if a logged-in user wants to see a location which is allowed only
260 for people with an 'admin' role, in your controller you can check it
265 if ($c->roles(qw/admin/)) {
266 $c->req->output("Your account has the role 'admin.'");
268 $c->req->output("You're not allowed to be here.");
272 One thing you might need is to forward non-authenticated users to a login
273 form if they try to access restricted areas. If you want to do this
274 controller-wide (if you have one controller for your admin section) then it's
275 best to add a user check to a '!begin' action:
277 sub begin : Private {
279 unless ($c->req->{user}) {
280 $c->req->action(undef); ## notice this!!
281 $c->forward('?login');
285 Pay attention to $c->req->action(undef). This is needed because of the
286 way $c->forward works - C<forward> to C<login> gets called, but after that
287 Catalyst will still execute the action defined in the URI (e.g. if you
288 tried to go to C</add>, then first 'begin' will forward to 'login', but after
289 that 'add' will nonetheless be executed). So $c->req->action(undef) undefines any
290 actions that were to be called and forwards the user where we want him/her
293 And this is all you need to do.
295 =head2 Pass-through login (and other actions)
297 An easy way of having assorted actions that occur during the processing of
298 a request that are orthogonal to its actual purpose - logins, silent
299 commands etc. Provide actions for these, but when they're required for
300 something else fill e.g. a form variable __login and have a sub begin like so:
302 sub begin : Private {
304 foreach my $action (qw/login docommand foo bar whatever/) {
305 if ($c->req->params->{"__${action}"}) {
306 $c->forward($action);
311 =head2 How to use Catalyst without mod_perl
313 Catalyst applications give optimum performance when run under mod_perl.
314 However sometimes mod_perl is not an option, and running under CGI is
315 just too slow. There's also an alternative to mod_perl that gives
316 reasonable performance named FastCGI.
320 To quote from L<http://www.fastcgi.com/>: "FastCGI is a language
321 independent, scalable, extension to CGI that provides high performance
322 without the limitations of specific server APIs." Web server support
323 is provided for Apache in the form of C<mod_fastcgi> and there is Perl
324 support in the C<FCGI> module. To convert a CGI Catalyst application
325 to FastCGI one needs to initialize an C<FCGI::Request> object and loop
326 while the C<Accept> method returns zero. The following code shows how
327 it is done - and it also works as a normal, single-shot CGI script.
334 my $request = FCGI::Request();
335 while ($request->Accept() >= 0) {
339 Any initialization code should be included outside the request-accept
342 There is one little complication, which is that C<MyApp-E<gt>run> outputs a
343 complete HTTP response including the status line (e.g.:
345 FastCGI just wants a set of headers, so the sample code captures the
346 output and drops the first line if it is an HTTP status line (note:
349 The Apache C<mod_fastcgi> module is provided by a number of Linux
350 distros and is straightforward to compile for most Unix-like systems.
351 The module provides a FastCGI Process Manager, which manages FastCGI
352 scripts. You configure your script as a FastCGI script with the
353 following Apache configuration directives:
356 AddHandler fastcgi-script fcgi
362 SetHandler fastcgi-script
363 Action fastcgi-script /path/to/fcgi-bin/fcgi-script
366 C<mod_fastcgi> provides a number of options for controlling the FastCGI
367 scripts spawned; it also allows scripts to be run to handle the
368 authentication, authorization, and access check phases.
370 For more information see the FastCGI documentation, the C<FCGI> module
371 and L<http://www.fastcgi.com/>.
373 =head2 Serving static content
375 Serving static content in Catalyst can be somewhat tricky; this recipe
376 shows one possible solution. Using this recipe will serve all static
377 content through Catalyst when developing with the built-in HTTP::Daemon
378 server, and will make it easy to use Apache to serve the content when
379 your app goes into production.
381 Static content is best served from a single directory within your root
382 directory. Having many different directories such as C<root/css> and
383 C<root/images> requires more code to manage, because you must separately
384 identify each static directory--if you decide to add a C<root/js>
385 directory, you'll need to change your code to account for it. In
386 contrast, keeping all static directories as subdirectories of a main
387 C<root/static> directory makes things much easier to manager. Here's an
388 example of a typical root directory structure:
392 root/controller/stuff.tt
395 root/static/css/main.css
396 root/static/images/logo.jpg
397 root/static/js/code.js
400 All static content lives under C<root/static> with everything else being
401 Template Toolkit files. Now you can identify the static content by
402 matching C<static> from within Catalyst.
404 =head3 Serving with HTTP::Daemon (myapp_server.pl)
406 To serve these files under the standalone server, we first must load the
407 Static plugin. Install L<Catalyst::Plugin::Static> if it's not already
410 In your main application class (MyApp.pm), load the plugin:
412 use Catalyst qw/-Debug FormValidator Static OtherPlugin/;
414 You will also need to make sure your end method does I<not> forward
415 static content to the view, perhaps like this:
418 my ( $self, $c ) = @_;
420 $c->forward( 'MyApp::V::TT' )
421 unless ( $c->res->body || !$c->stash->{template} );
424 This code will only forward to the view if a template has been
425 previously defined by a controller and if there is not already data in
426 C<$c-E<gt>res-E<gt>body>.
428 Next, create a controller to handle requests for the /static path. Use
429 the Helper to save time. This command will create a stub controller as
430 C<lib/MyApp/C/Static.pm>.
432 $ script/myapp_create.pl controller Static
434 Edit the file and add the following methods:
436 # serve all files under /static as static files
437 sub default : Path('/static') {
438 my ( $self, $c ) = @_;
440 # Optional, allow the browser to cache the content
441 $c->res->headers->header( 'Cache-Control' => 'max-age=86400' );
443 $c->serve_static; # from Catalyst::Plugin::Static
446 # also handle requests for /favicon.ico
447 sub favicon : Path('/favicon.ico') {
448 my ( $self, $c ) = @_;
453 You can also define a different icon for the browser to use instead of
454 favicon.ico by using this in your HTML header:
456 <link rel="icon" href="/static/myapp.ico" type="image/x-icon" />
459 =head3 Common problems
461 The Static plugin makes use of the C<shared-mime-info> package to
462 automatically determine MIME types. This package is notoriously
463 difficult to install, especially on win32 and OSX. For OSX the easiest
464 path might be to install Fink, then use C<apt-get install
465 shared-mime-info>. Restart the server, and everything should be fine.
467 Make sure you are using the latest version (>= 0.16) for best
468 results. If you are having errors serving CSS files, or if they get
469 served as text/plain instead of text/css, you may have an outdated
470 shared-mime-info version. You may also wish to simply use the following
471 code in your Static controller:
473 if ($c->req->path =~ /css$/i) {
474 $c->serve_static( "text/css" );
479 =head3 Serving with Apache
481 When using Apache, you can completely bypass Catalyst and the Static
482 controller by intercepting requests for the C<root/static> path at the
483 server level. All that is required is to define a DocumentRoot and add a
484 separate Location block for your static content. Here is a complete
485 config for this application under mod_perl 1.x; variations, some of
486 which could be simpler, are left as an exercise for the reader:
489 use lib qw(/var/www/MyApp/lib);
494 ServerName myapp.example.com
495 DocumentRoot /var/www/MyApp/root
497 SetHandler perl-script
500 <LocationMatch "/(static|favicon.ico)">
501 SetHandler default-handler
505 =head2 Forwarding with arguments
507 Sometimes you want to pass along arguments when forwarding to another
508 action. This can be accomplished by simply setting the arguments before
511 $c->req->args([qw/arg1 arg2 arg3/]);
512 $c->forward('/wherever');
516 Sebastian Riedel, C<sri@oook.de>
517 Danijel Milicevic, C<me@danijel.de>
518 Viljo Marrandi, C<vilts@yahoo.com>
519 Marcus Ramberg, C<mramberg@cpan.org>
520 Andy Grundman, C<andy@hybridized.org>
524 This program is free software, you can redistribute it and/or modify it
525 under the same terms as Perl itself.