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 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.

cpanm Catalyst::Runtime

perl -MCPAN -e shell
install Catalyst::Runtime