


Catalyst::EnginUserGContributed Perl DocCatalyst::Engine::CGI(3p)


NAME
       Catalyst::Engine::CGI - The CGI Engine

SYNOPSIS
       A script using the Catalyst::Engine::CGI module might look like:

           #!/usr/bin/perl -w

           use strict;
           use lib '/path/to/MyApp/lib';
           use MyApp;

           MyApp->run;

       The application module ("MyApp") would use "Catalyst", which loads the
       appropriate engine module.

DESCRIPTION
       This is the Catalyst engine specialized for the CGI environment.

PATH DECODING
       Most web server environments pass the requested path to the application
       using environment variables, from which Catalyst has to reconstruct the
       request base (i.e. the top level path to / in the application, exposed
       as "$c->request->base") and the request path below that base.

       There are two methods of doing this, both of which have advantages and
       disadvantages. Which method is used is determined by the
       "$c->config(use_request_uri_for_path)" setting (which can either be
       true or false).

   use_request_uri_for_path => 0
       This is the default (and the) traditional method that Catalyst has used
       for determining the path information.  The path is synthesised from a
       combination of the "PATH_INFO" and "SCRIPT_NAME" environment variables.
       The allows the application to behave correctly when "mod_rewrite" is
       being used to redirect requests into the application, as these
       variables are adjusted by mod_rewrite to take account for the redirect.

       However this method has the major disadvantage that it is impossible to
       correctly decode some elements of the path, as RFC 3875 says: ""Unlike
       a URI path, the PATH_INFO is not URL-encoded, and cannot contain
       path-segment parameters."" This means PATH_INFO is always decoded, and
       therefore Catalyst can't distinguish / vs %2F in paths (in addition to
       other encoded values).

   use_request_uri_for_path => 1
       This method uses the "REQUEST_URI" and "SCRIPT_NAME" environment
       variables. As "REQUEST_URI" is never decoded, this means that
       applications using this mode can correctly handle URIs including the
       %2F character (i.e. with "AllowEncodedSlashes" set to "On" in Apache).

       Given that this method of path resolution is provably more correct, it
       is recommended that you use this unless you have a specific need to



perl v5.12.2                2010-05-15                          1





Catalyst::EnginUserGContributed Perl DocCatalyst::Engine::CGI(3p)


       deploy your application in a non-standard environment, and you are
       aware of the implications of not being able to handle encoded URI paths
       correctly.

       However it also means that in a number of cases when the app isn't
       installed directly at a path, but instead is having paths rewritten
       into it (e.g. as a .cgi/fcgi in a public_html directory, with
       mod_rewrite in a .htaccess file, or when SSI is used to rewrite pages
       into the app, or when sub-paths of the app are exposed at other URIs
       than that which the app is 'normally' based at with "mod_rewrite"), the
       resolution of "$c->request->base" will be incorrect.

OVERLOADED METHODS
       This class overloads some methods from "Catalyst::Engine".

   $self->finalize_headers($c)
   $self->prepare_connection($c)
   $self->prepare_headers($c)
   $self->prepare_path($c)
   $self->prepare_query_parameters($c)
   $self->prepare_request($c, (env => \%env))
   $self->prepare_write($c)
       Enable autoflush on the output handle for CGI-based engines.

   $self->write($c, $buffer)
       Writes the buffer to the client.

   $self->read_chunk($c, $buffer, $length)
   $self->run
SEE ALSO
       Catalyst, Catalyst::Engine

AUTHORS
       Catalyst Contributors, see Catalyst.pm

COPYRIGHT
       This library is free software. You can redistribute it and/or modify it
       under the same terms as Perl itself.



















perl v5.12.2                2010-05-15                          2


