X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=d4641fcf1cdfe821e2a6ba1d8d01a4b9549fc89f;hb=1c61c726cbf3a9ee7ffa15299e34a8700383e670;hp=7902a6039aceba4d9f73c5deeb3c158601f2eade;hpb=dd16873caa911e99f13e9e509ba242fdf19ead67;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod index 7902a60..d4641fc 100644 --- a/lib/Catalyst/Manual/Cookbook.pod +++ b/lib/Catalyst/Manual/Cookbook.pod @@ -20,6 +20,11 @@ placing a die() call in the _end action. } ); +If you're tired of removing and adding this all the time, you +can easily add a condition. for example: + + die "Testing" if $c->param->{dump_info}; + =head2 Disable statistics Just add this line to your application class if you don't want those nifty @@ -135,28 +140,232 @@ module: $CGI::Simple::POST_MAX = 1048576000; +=head2 Authentication with Catalyst::Plugin::Authentication::CDBI + +There are (at least) two ways to implement authentication with this plugin: +1) only checking username and password +2) checking username, password and the roles the user has + +For both variants you'll need the following code in your MyApp package: + + use Catalyst qw/Session::FastMmap Static Authentication::CDBI/; + + MyApp->config( authentication => { user_class => 'MyApp::M::MyApp::Users', + user_field => 'email', + password_field => 'password' }); + +'user_class' is a Class::DBI class for your users table. +'user_field' tells which field is used for username lookup (might be +email, first name, surname etc). +'password_field' is, well, password field in your table and by default +password is stored in plain text. Authentication::CDBI looks for 'user' +and 'password' fields in table, if they're not defined in the config. + +In PostgreSQL users table might be something like: + +CREATE TABLE users ( + user_id serial, + name varchar(100), + surname varchar(100), + password varchar(100), + email varchar(100), + primary key(user_id) +); + +We'll discuss the first variant for now: +1. user:password login / auth without roles + +To log in a user you might use a action like this: + + '?login' => sub { + my ($self, $c) = @_; + if ($c->req->params->{username}) { + $c->session_login($c->req->params->{username}, + $c->req->params->{password} ); + if ($c->req->{user}) { + $c->forward('?restricted_area'); + } + } + }, + +$c->req->params->{username} and $c->req->params->{password} are html +form parameters from a login form. If login succeeds, then $c->req->{user} +contains the username of the authenticated user. + +If you want to remember the users login status inbetween further requests, +then just use the $c->session_login method, Catalyst will create a session +id, session cookie and automatically append session id to all urls. So +all you have to do, is just check $c->req->{user} where needed. + +To log out user, just call $c->session_logout. + +Now lets take a look at the second variant: +2. user:password login / auth with roles + +To use roles you need to add to MyApp->config in the 'authentication' +section following parameters: + + role_class => 'MyApp::M::MyApp::Roles', + user_role_class => 'MyApp::M::MyApp::UserRoles', + user_role_user_field => 'user_id', + user_role_role_field => 'role_id', + +Corresponding tables in PostgreSQL could look like this: + +CREATE TABLE roles ( + role_id serial, + name varchar(100), + primary key(role_id) +); + +CREATE TABLE user_roles ( + user_role_id serial, + user_id int, + role_id int, + primary key(user_role_id), + foreign key(user_id) references users(user_id), + foreign key(role_id) references roles(role_id) +); + +The 'roles' table is a list of role names and the 'user_role' table is used for +the user -> role lookup. + +Now if a logged in user wants to see a location which is allowed only for +people with 'admin' role then in you controller you can check it with: + + '?add' => sub { + my ($self, $c) = @_; + if ($c->roles(qw/admin/)) { + $c->req->output("Your account has the role 'admin.'"); + } else { + $c->req->output("You're not allowed to be here"); + } + }, + +One thing you might need is to forward non-authenticated users to login +form, if they try to access restricted areas. If you want to do this +controller-wide (if you have one controller for admin section) then it's +best to add user check to '!begin' action: + + '!begin' => sub { + my ($self, $c) = @_; + unless ($c->req->{user}) { + $c->req->action(undef); ## notice this!! + $c->forward('?login'); + } + }, + +Pay attention to $c->req->action(undef). This is needed, because of the +way $c->forward works - forward to login gets called, but after that +Catalyst executes anyway the action defined in the uri (eg. if you tried to +watch /add, then first '!begin' forwards to '?login', but after that +anyway '?add' is executed). So $c->req->action(undef) undefines any +actions that were to be called and forwards user where we want him/her +to be. + +And this is all you need to do, isn't Catalyst wonderful? + + +=head2 How to use Catalyst without mod_perl -=head2 Easily working with datetime objects. +Catalyst applications give optimum performance when run under mod_perl. +However sometimes mod_perl is not an option, and running under CGI is just too +slow. There are two alternatives to mod_perl that give reasonable +performance: FastCGI and PersistentPerl. -If you store datetime data in your tables, you can easily expand this column to -a L object which lets you call useful methods like ymd, mon and -datetime on it. +B + +To quote from L: "FastCGI is a language independent, +scalable, extension to CGI that provides high performance without the +limitations of specific server APIs." Web server support is provided for +Apache in the form of C and there is Perl support in the C +module. To convert a CGI Catalyst application to FastCGI one needs to +initialize an C object and loop while the C method +returns zero. The following code shows how it is done - and it also works as +a normal, single-shot CGI script. + + #!/usr/bin/perl + use strict; + use FCGI; + use MyApp; + + my $request = FCGI::Request(); + while ($request->Accept() >= 0) { + MyApp->run; + } + +Any initialization code should be included outside the request-accept loop. + +There is one little complication, which is that Crun> outputs a +complete HTTP response including the status line (e.g.: "C"). +FastCGI just wants a set of headers, so the sample code captures the output +and drops the first line if it is an HTTP status line (note: this may change). + +The Apache C module is provided by a number of Linux distros and +is straightforward to compile for most Unix-like systems. The module provides +a FastCGI Process Manager, which manages FastCGI scripts. You configure your +script as a FastCGI script with the following Apache configuration directives: + + + AddHandler fastcgi-script fcgi + + +or: + + + SetHandler fastcgi-script + Action fastcgi-script /path/to/fcgi-bin/fcgi-script + + +C provides a number of options for controlling the FastCGI +scripts spawned; it also allows scripts to be run to handle the +authentication, authorization and access check phases. + +For more information see the FastCGI documentation, the C module and +L. + + +B + +PersistentPerl (previously known as C) is a persistent Perl +interpreter. After the script is initially run, instead of exiting, the perl +interpreter is kept running. During subsequent runs, this interpreter is used +to handle new executions instead of starting a new perl interpreter each +time. A very fast frontend program contacts the persistent Perl process, which +is usually already running, to do the work and return the results. +PersistentPerl can be used to speed up perl CGI scripts. It also provides an +Apache module so that scripts can be run without the overhead of doing a +fork/exec for each request. + +The code for PersistentPerl is simpler than for FastCGI; rather than waiting +in an accept loop the script runs to completion, however variables are not +reinitialized on subsequent runs but maintain their values from the previous +run. + + + #!/usr/bin/perperl + use strict; + use vars qw($output $initialized); + use PersistentPerl; + use MyApp; + + if (!$initialized++) { + # initialization code - set up database, etc + if ($PersistentPerl::i_am_per_perl) { + # PP-specific initialization code + } + } -In order to set it up, add something like the following to your CDBI Model Class: + MyApp->run; - __PACKAGE__->has_a( - mycolumn => 'Time::Piece', - inflate => sub { Time::Piece->strptime( shift, "%FT%H:%M:%S" ) }, - deflate => 'datetime' - ); +For more information see the C documentation. -If you want to use another format in the database, you can change the strptime call -to fit your format, and use strftime to return it with your custom format to the -database during deflate. See the L and L docs for more info. =head1 AUTHOR Sebastian Riedel, C +Danijel Milicevic C +Viljo Marrandi C =head1 COPYRIGHT