=head1 DESCRIPTION
-Yummy!
+Yummy code like your mum used to bake!
=head1 RECIPES
}
);
+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
Modify the $c->form() parameters to match your needs, and don't forget to copy
the templates. ;)
+=head2 Serving static files and CSS as text/css
+
+If you want to serve static content (like images, txt or CSS) via Catalyst,
+then all you need is the plugin Catalyst::Plugin::Static as well as a small
+regex to set the MIME type for CSS to text/css.
+
+ # lib/MyApp.pm
+ package MyApp;
+
+ use strict;
+ use Catalyst qw/-Debug Static/;
+
+ __PACKAGE__->action(
+
+ '!default' => sub {
+ my ( $self, $c ) = @_;
+ $c->serve_static;
+ },
+
+ '/^.*\.css$/' => sub {
+ my ( $self, $c ) = @_;
+ $c->serve_static('text/css');
+ },
+ );
+
+=head2 Uploads with Catalyst
+
+To implement uploads in Catalyst you need to have a HTML form similiar to
+this:
+
+ <form action="/upload" method="post" enctype="multipart/form-data">
+ <input type="hidden" name="form_submit" value="yes">
+ <input type="file" name="my_file">
+ <input type="submit" value="Send">
+ </form>
+
+It's very important not to forget enctype="multipart/form-data" in form,
+if it's not there, uploads just don't work.
+
+Catalyst Controller module 'upload' action:
+
+ MyApp->action(
+
+ 'upload' => sub {
+ my ($self, $c) = @_;
+ if ($c->req->parameters->{form_submit} eq 'yes') {
+ my $filename = $c->req->parameters->{my_file};
+ if ($filename) {
+ my $fh = $c->req->uploads->{$filename}->{fh};
+ open(NEW_FILE, ">/tmp/$filename") or die
+ "Can't open file for writing: $!";
+ while ($fh->read(my $buf, 32768)) {
+ print NEW_FILE $buf;
+ }
+ close(NEW_FILE);
+ }
+ }
+ $c->stash->{template} = 'upload_form.tt';
+ $c->forward('MyApp::V::View');
+ },
+ );
+
+If you want to upload bigger files than 1MB, then just add to your Controller
+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
+
+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.
+
+B<Using FastCGI>
+
+To quote from L<http://www.fastcgi.com/>: "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<mod_fastcgi> and there is Perl support in the C<FCGI>
+module. To convert a CGI Catalyst application to FastCGI one needs to
+initialize an C<FCGI::Request> object and loop while the C<Accept> 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 C<MyApp->run> outputs a
+complete HTTP response including the status line (e.g.: "C<HTTP/1.1 200>").
+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<mod_fastcgi> 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:
+
+ <Location /fcgi-bin>
+ AddHandler fastcgi-script fcgi
+ </Location>
+
+or:
+
+ <Location /fcgi-bin>
+ SetHandler fastcgi-script
+ Action fastcgi-script /path/to/fcgi-bin/fcgi-script
+ </Location>
+
+C<mod_fastcgi> 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<FCGI> module and
+L<http://www.fastcgi.com/>.
+
+
+B<PersistentPerl>
+
+PersistentPerl (previously known as C<CGI::SpeedyCGI>) 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
+ }
+ }
+
+ MyApp->run;
+
+For more information see the C<PersistentPerl> documentation.
+
+
=head1 AUTHOR
Sebastian Riedel, C<sri@oook.de>
+Danijel Milicevic C<me@danijel.de>
+Viljo Marrandi C<vilts@yahoo.com>
=head1 COPYRIGHT
projects / catagits/Catalyst-Runtime.git / blobdiff