X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=b6913a7beededbda8b0ea83df46edd96d7f6269e;hb=b248fa4a4191cd3eaa13d72e6ec8e64dfef973e0;hp=0410d790a46ef837e300e6fe0d1247a692228844;hpb=121baf930c9edc6187e05e3f168ff56502d9af34;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod index 0410d79..b6913a7 100644 --- a/lib/Catalyst/Manual/Cookbook.pod +++ b/lib/Catalyst/Manual/Cookbook.pod @@ -74,16 +74,16 @@ Catalyst Controller module 'upload' action: if ( $c->request->parameters->{form_submit} eq 'yes' ) { if ( my $upload = $c->request->upload('my_file') ) { - + my $filename = $upload->filename; my $target = "/tmp/upload/$filename"; - + unless ( $upload->link_to($target) || $upload->copy_to($target) ) { die( "Failed to copy '$filename' to '$target': $!" ); } } } - + $c->stash->{template} = 'file_upload.html'; } @@ -113,7 +113,7 @@ And in the controller: my $upload = $c->req->upload($field); my $filename = $upload->filename; my $target = "/tmp/upload/$filename"; - + unless ( $upload->link_to($target) || $upload->copy_to($target) ) { die( "Failed to copy '$filename' to '$target': $!" ); } @@ -343,7 +343,7 @@ authentication, authorization, and access check phases. For more information see the FastCGI documentation, the C module and L. - + =head2 Serving static content Serving static content in Catalyst can be somewhat tricky; this recipe @@ -410,7 +410,7 @@ Edit the file and add the following methods: # serve all files under /static as static files sub default : Path('/static') { my ( $self, $c ) = @_; - + # Optional, allow the browser to cache the content $c->res->headers->header( 'Cache-Control' => 'max-age=86400' ); @@ -420,7 +420,7 @@ Edit the file and add the following methods: # also handle requests for /favicon.ico sub favicon : Path('/favicon.ico') { my ( $self, $c ) = @_; - + $c->serve_static; } @@ -461,7 +461,7 @@ config for this application under mod_perl 1.x: use lib qw(/var/www/MyApp/lib); PerlModule MyApp - + ServerName myapp.example.com DocumentRoot /var/www/MyApp/root @@ -495,8 +495,8 @@ the Catalyst Request object: $c->req->args([qw/arg1 arg2 arg3/]); $c->forward('/wherever'); -(See L for more information on -passing arguments via C.) +(See the L Flow_Control section for more +information on passing arguments via C.) =head2 Configure your application @@ -594,21 +594,21 @@ C method; see L). sub end : Private { my ( $self, $c ) = @_; - + if ( scalar @{ $c->error } ) { $c->stash->{errors} = $c->error; $c->stash->{template} = 'errors.tt'; $c->forward('MyApp::View::TT'); $c->error(0); } - + return 1 if $c->response->status =~ /^3\d\d$/; return 1 if $c->response->body; - + unless ( $c->response->content_type ) { $c->response->content_type('text/html; charset=utf-8'); } - + $c->forward('MyApp::View::TT'); } @@ -628,13 +628,18 @@ in your Catalyst application, then make the following changes: =head3 lib/MyApp.pm - use Catalyst qw/Session::FastMmap Authentication::CDBI/; + use Catalyst qw/ + Authentication + Authentication::Store::DBIC + Authentication::Credential::Password + /; - __PACKAGE__->config->{authentication} = { - 'user_class' => 'ScratchPad::M::MyDB::Customer', + __PACKAGE__->config->{authentication}->{dbic} = { + 'user_class' => 'My::Model::DBIC::User', 'user_field' => 'username', - 'password_field' => 'password', - 'password_hash' => '', + 'password_field' => 'password' + 'password_type' => 'hashed', + 'password_hash_type'=> 'SHA-1' }; sub auto : Private { @@ -642,25 +647,17 @@ in your Catalyst application, then make the following changes: my $login_path = 'user/login'; # allow people to actually reach the login page! - if ($c->req->path eq $login_path) { + if ($c->request->path eq $login_path) { return 1; } - # if we have a user ... we're OK - if ( $c->req->user ) { - $c->session->{'authed_user'} = - MyApp::M::MyDB::Customer->retrieve( - 'username' => $c->req->user - ); - } - - # otherwise they're not logged in - else { + # if a user doesn't exist, force login + if ( !$c->user_exists ) { # force the login screen to be shown - $c->res->redirect($c->req->base . $login_path); + $c->response->redirect($c->request->base . $login_path); } - # continue with the processing chain + # otherwise, we have a user - continue with the processing chain return 1; } @@ -674,35 +671,32 @@ in your Catalyst application, then make the following changes: # default form message $c->stash->{'message'} = 'Please enter your username and password'; - if ( $c->req->param('username') ) { + if ( $c->request->param('username') ) { # try to log the user in - $c->session_login( - $c->req->param('username'), - $c->req->param('password'), - ); - - # if we have a user we're logged in - if ( $c->req->user ) { - $c->res->redirect('/some/page'); + # login() is provided by ::Authentication::Credential::Password + if( $c->login( + $c->request->param('username'), + $c->request->param('password'), + ); + + # if login() returns 1, user is now logged in + $c->response->redirect('/some/page'); } # otherwise we failed to login, try again! - else { - $c->stash->{'message'} = - 'Unable to authenticate the login details supplied'; - } + $c->stash->{'message'} = + 'Unable to authenticate the login details supplied'; } } sub logout : Path('/user/logout') { my ($self, $c) = @_; - # logout the session, and remove information we've stashed - $c->session_logout; - delete $c->session->{'authed_user'}; + # log the user out + $c->logout; # do the 'default' action - $c->res->redirect($c->req->base); -} + $c->response->redirect($c->request->base); + } =head3 root/base/user/login.tt @@ -720,6 +714,66 @@ in your Catalyst application, then make the following changes: [% INCLUDE footer.tt %] +=head2 Role-based Authorization + +For more advanced access control, you may want to consider using role-based +authorization. This means you can assign different roles to each user, e.g. +"user", "admin", etc. + +The C and C methods and view template are exactly the same as +in the previous example. + +The L plugin is required when +implementing roles: + + use Catalyst qw/ + Authentication + Authentication::Credential::Password + Authentication::Store::Htpasswd + Authorization::Roles + /; + +Roles are implemented automatically when using +L: + + # no additional role configuration required + __PACKAGE__->config->{authentication}{htpasswd} = "passwdfile"; + +Or can be set up manually when using L: + + # Authorization using a many-to-many role relationship + __PACKAGE__->config->{authorization}{dbic} = { + 'role_class' => 'My::Model::DBIC::Role', + 'role_field' => 'name', + 'user_role_user_field' => 'user', + + # DBIx::Class only (omit if using Class::DBI) + 'role_rel' => 'user_role', + + # Class::DBI only, (omit if using DBIx::Class) + 'user_role_class' => 'My::Model::CDBI::UserRole' + 'user_role_role_field' => 'role', + }; + +To restrict access to any action, you can use the C method: + + sub restricted : Local { + my ( $self, $c ) = @_; + + $c->detach("unauthorized") + unless $c->check_user_roles( "admin" ); + + # do something restricted here + } + +You can also use the C method. This just gives an error if +the current user does not have one of the required roles: + + sub also_restricted : Global { + my ( $self, $c ) = @_; + $c->assert_user_roles( qw/ user admin / ); + } + =head1 AUTHOR Sebastian Riedel, C @@ -729,6 +783,7 @@ Marcus Ramberg, C Jesse Sheidlower, C Andy Grundman, C Chisel Wright, C +Will Hawes, C =head1 COPYRIGHT