view release on metacpan or  search on metacpan

lib/Catalyst.pm  view on Meta::CPAN

Using this type of injection allows you to construct significant amounts of your application
with only configuration!.  This may or may not lead to increased code understanding.

Please not you may also call the ->inject_components application method as well, although
you must do so BEFORE setup.

=back

=head1 EXCEPTIONS

Generally when you throw an exception inside an Action (or somewhere in
your stack, such as in a model that an Action is calling) that exception
is caught by Catalyst and unless you either catch it yourself (via eval
or something like L<Try::Tiny> or by reviewing the L</error> stack, it
will eventually reach L</finalize_errors> and return either the debugging
error stack page, or the default error page.  However, if your exception
can be caught by L<Plack::Middleware::HTTPExceptions>, L<Catalyst> will
instead rethrow it so that it can be handled by that middleware (which
is part of the default middleware).  For example this would allow

    use HTTP::Throwable::Factory 'http_throw';

    sub throws_exception :Local {
      my ($self, $c) = @_;

      http_throw(SeeOther => { location =>
        $c->uri_for($self->action_for('redirect')) });

    }

=head1 INTERNAL ACTIONS

Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
C<_ACTION>, and C<_END>. These are by default not shown in the private
action table, but you can make them visible with a config parameter.

    MyApp->config(show_internal_actions => 1);

=head1 ON-DEMAND PARSER

The request body is usually parsed at the beginning of a request,
but if you want to handle input yourself, you can enable on-demand
parsing with a config parameter.

    MyApp->config(parse_on_demand => 1);

=head1 PROXY SUPPORT

Many production servers operate using the common double-server approach,
with a lightweight frontend web server passing requests to a larger
backend server. An application running on the backend server must deal
with two problems: the remote user always appears to be C<127.0.0.1> and
the server's hostname will appear to be C<localhost> regardless of the
virtual host that the user connected through.

Catalyst will automatically detect this situation when you are running
the frontend and backend servers on the same machine. The following
changes are made to the request.

    $c->req->address is set to the user's real IP address, as read from
    the HTTP X-Forwarded-For header.

    The host value for $c->req->base and $c->req->uri is set to the real
    host, as read from the HTTP X-Forwarded-Host header.

Additionally, you may be running your backend application on an insecure
connection (port 80) while your frontend proxy is running under SSL.  If there
is a discrepancy in the ports, use the HTTP header C<X-Forwarded-Port> to
tell Catalyst what port the frontend listens on.  This will allow all URIs to
be created properly.

In the case of passing in:

    X-Forwarded-Port: 443

All calls to C<uri_for> will result in an https link, as is expected.

Obviously, your web server must support these headers for this to work.

In a more complex server farm environment where you may have your
frontend proxy server(s) on different machines, you will need to set a
configuration option to tell Catalyst to read the proxied data from the
headers.

    MyApp->config(using_frontend_proxy => 1);

If you do not wish to use the proxy support at all, you may set:

    MyApp->config(ignore_frontend_proxy => 1);

=head2 Note about psgi files

Note that if you supply your own .psgi file, calling
C<< MyApp->psgi_app(@_); >>, then B<this will not happen automatically>.

You either need to apply L<Plack::Middleware::ReverseProxy> yourself
in your psgi, for example:

    builder {
        enable "Plack::Middleware::ReverseProxy";
        MyApp->psgi_app
    };

This will unconditionally add the ReverseProxy support, or you need to call
C<< $app = MyApp->apply_default_middlewares($app) >> (to conditionally
apply the support depending upon your config).

See L<Catalyst::PSGI> for more information.

=head1 THREAD SAFETY

Catalyst has been tested under Apache 2's threading C<mpm_worker>,
C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
believe the Catalyst core to be thread-safe.

If you plan to operate in a threaded environment, remember that all other
modules you are using must also be thread-safe. Some modules, most notably
L<DBD::SQLite>, are not thread-safe.

=head1 DATA HANDLERS