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 request by
14 placing a die() call in the _end action.
17 my ( $self, $c ) = @_;
21 If you're tired of removing and adding this all the time, you
22 can easily add a condition. for example:
24 die "Testing" if $c->param->{dump_info};
26 =head2 Disable statistics
28 Just add this line to your application class if you don't want those nifty
29 statistics in your debug messages.
31 sub Catalyst::Log::info { }
35 Scaffolding is very simple with Catalyst.
36 Just use Catalyst::Model::CDBI::CRUD as baseclass.
38 # lib/MyApp/Model/CDBI.pm
39 package MyApp::Model::CDBI;
42 use base 'Catalyst::Model::CDBI::CRUD';
45 dsn => 'dbi:SQLite:/tmp/myapp.db',
54 use Catalyst 'FormValidator';
57 name => 'My Application',
58 root => '/home/joeuser/myapp/root'
61 sub my_table : Global {
62 my ( $self, $c ) = @_;
63 $c->form( optional => [ MyApp::Model::CDBI::Table->columns ] );
64 $c->forward('MyApp::Model::CDBI::Table');
69 Modify the $c->form() parameters to match your needs, and don't forget to copy
72 =head2 Uploads with Catalyst
74 To implement uploads in Catalyst you need to have a HTML form similiar to
77 <form action="/upload" method="post" enctype="multipart/form-data">
78 <input type="hidden" name="form_submit" value="yes">
79 <input type="file" name="my_file">
80 <input type="submit" value="Send">
83 It's very important not to forget enctype="multipart/form-data" in form,
84 if it's not there, uploads just don't work.
86 Catalyst Controller module 'upload' action:
90 if ($c->req->parameters->{form_submit} eq 'yes') {
91 my $filename = $c->req->parameters->{my_file};
93 my $fh = $c->req->uploads->{$filename}->{fh};
94 open(NEW_FILE, ">/tmp/$filename") or die
95 "Can't open file for writing: $!";
96 while ($fh->read(my $buf, 32768)) {
102 $c->stash->{template} = 'upload_form.tt';
103 $c->forward('MyApp::V::View');
106 If you want to upload bigger files than 1MB, then just add to your Controller
109 $CGI::Simple::POST_MAX = 1048576000;
111 =head2 Authentication with Catalyst::Plugin::Authentication::CDBI
113 There are (at least) two ways to implement authentication with this plugin:
114 1) only checking username and password
115 2) checking username, password and the roles the user has
117 For both variants you'll need the following code in your MyApp package:
119 use Catalyst qw/Session::FastMmap Static Authentication::CDBI/;
121 MyApp->config( authentication => { user_class => 'MyApp::M::MyApp::Users',
122 user_field => 'email',
123 password_field => 'password' });
125 'user_class' is a Class::DBI class for your users table.
126 'user_field' tells which field is used for username lookup (might be
127 email, first name, surname etc).
128 'password_field' is, well, password field in your table and by default
129 password is stored in plain text. Authentication::CDBI looks for 'user'
130 and 'password' fields in table, if they're not defined in the config.
132 In PostgreSQL users table might be something like:
137 surname varchar(100),
138 password varchar(100),
143 We'll discuss the first variant for now:
144 1. user:password login / auth without roles
146 To log in a user you might use a action like this:
148 sub 'login' : Local {
150 if ($c->req->params->{username}) {
151 $c->session_login($c->req->params->{username},
152 $c->req->params->{password} );
153 if ($c->req->{user}) {
154 $c->forward('?restricted_area');
159 $c->req->params->{username} and $c->req->params->{password} are html
160 form parameters from a login form. If login succeeds, then
161 $c->req->{user} contains the username of the authenticated user.
163 If you want to remember the users login status inbetween further
164 requests, then just use the $c->session_login method, Catalyst will
165 create a session id, session cookie and automatically append session
166 id to all urls. So all you have to do, is just check $c->req->{user}
169 To log out user, just call $c->session_logout.
171 Now lets take a look at the second variant:
172 2. user:password login / auth with roles
174 To use roles you need to add to MyApp->config in the 'authentication'
175 section following parameters:
177 role_class => 'MyApp::M::MyApp::Roles',
178 user_role_class => 'MyApp::M::MyApp::UserRoles',
179 user_role_user_field => 'user_id',
180 user_role_role_field => 'role_id',
182 Corresponding tables in PostgreSQL could look like this:
190 CREATE TABLE user_roles (
194 primary key(user_role_id),
195 foreign key(user_id) references users(user_id),
196 foreign key(role_id) references roles(role_id)
199 The 'roles' table is a list of role names and the 'user_role' table is
200 used for the user -> role lookup.
202 Now if a logged in user wants to see a location which is allowed only
203 for people with 'admin' role then in you controller you can check it
208 if ($c->roles(qw/admin/)) {
209 $c->req->output("Your account has the role 'admin.'");
211 $c->req->output("You're not allowed to be here");
215 One thing you might need is to forward non-authenticated users to login
216 form, if they try to access restricted areas. If you want to do this
217 controller-wide (if you have one controller for admin section) then it's
218 best to add user check to '!begin' action:
220 sub begin : Private {
222 unless ($c->req->{user}) {
223 $c->req->action(undef); ## notice this!!
224 $c->forward('?login');
228 Pay attention to $c->req->action(undef). This is needed, because of the
229 way $c->forward works - forward to login gets called, but after that
230 Catalyst executes anyway the action defined in the uri (eg. if you
231 tried to watch /add, then first 'begin' forwards to 'login', but after
232 that anyway 'add' is executed). So $c->req->action(undef) undefines any
233 actions that were to be called and forwards user where we want him/her
236 And this is all you need to do, isn't Catalyst wonderful?
239 =head2 How to use Catalyst without mod_perl
241 Catalyst applications give optimum performance when run under mod_perl.
242 However sometimes mod_perl is not an option, and running under CGI is
243 just too slow. There are two alternatives to mod_perl that give
244 reasonable performance: FastCGI and PersistentPerl.
248 To quote from L<http://www.fastcgi.com/>: "FastCGI is a language
249 independent, scalable, extension to CGI that provides high performance
250 without the limitations of specific server APIs." Web server support
251 is provided for Apache in the form of C<mod_fastcgi> and there is Perl
252 support in the C<FCGI> module. To convert a CGI Catalyst application
253 to FastCGI one needs to initialize an C<FCGI::Request> object and loop
254 while the C<Accept> method returns zero. The following code shows how
255 it is done - and it also works as a normal, single-shot CGI script.
262 my $request = FCGI::Request();
263 while ($request->Accept() >= 0) {
267 Any initialization code should be included outside the request-accept
270 There is one little complication, which is that C<MyApp->run> outputs a
271 complete HTTP response including the status line (e.g.:
273 FastCGI just wants a set of headers, so the sample code captures the
274 output and drops the first line if it is an HTTP status line (note:
277 The Apache C<mod_fastcgi> module is provided by a number of Linux
278 distros and is straightforward to compile for most Unix-like systems.
279 The module provides a FastCGI Process Manager, which manages FastCGI
280 scripts. You configure your script as a FastCGI script with the
281 following Apache configuration directives:
284 AddHandler fastcgi-script fcgi
290 SetHandler fastcgi-script
291 Action fastcgi-script /path/to/fcgi-bin/fcgi-script
294 C<mod_fastcgi> provides a number of options for controlling the FastCGI
295 scripts spawned; it also allows scripts to be run to handle the
296 authentication, authorization and access check phases.
298 For more information see the FastCGI documentation, the C<FCGI> module
299 and L<http://www.fastcgi.com/>.
304 PersistentPerl (previously known as C<CGI::SpeedyCGI>) is a persistent
305 Perl interpreter. After the script is initially run, instead of
306 exiting, the perl interpreter is kept running. During subsequent runs,
307 this interpreter is used to handle new executions instead of starting
308 a new perl interpreter each time. A very fast frontend program contacts
309 the persistent Perl process, which is usually already running, to do
310 the work and return the results.
311 PersistentPerl can be used to speed up perl CGI scripts. It also
312 provides an Apache module so that scripts can be run without the
313 overhead of doing a fork/exec for each request.
315 The code for PersistentPerl is simpler than for FastCGI; rather than
316 waiting in an accept loop the script runs to completion, however
317 variables are not reinitialized on subsequent runs but maintain their
318 values from the previous run.
323 use vars qw($output $initialized);
327 if (!$initialized++) {
328 # initialization code - set up database, etc
329 if ($PersistentPerl::i_am_per_perl) {
330 # PP-specific initialization code
336 For more information see the C<PersistentPerl> documentation.
341 Sebastian Riedel, C<sri@oook.de>
342 Danijel Milicevic C<me@danijel.de>
343 Viljo Marrandi C<vilts@yahoo.com>
344 Marcus Ramberg C<mramberg@cpan.org>
348 This program is free software, you can redistribute it and/or modify it
349 under the same terms as Perl itself.