Catalyst-Runtime
14 results

 view release on metacpan or  search on metacpan

lib/Catalyst.pm  view on Meta::CPAN 

reference of your Catalyst application for use in a custom F<.psgi> or in your
own created server modules.

=cut

*to_app = \&psgi_app;

sub psgi_app {
    my ($app) = @_;
    my $psgi = $app->engine->build_psgi_app($app);
    return $app->Catalyst::Utils::apply_registered_middleware($psgi);
}

=head2 $c->setup_home

Sets up the home directory.

=cut

sub setup_home {
    my ( $class, $home ) = @_;

    if ( my $env = Catalyst::Utils::env_value( $class, 'HOME' ) ) {
        $home = $env;
    }

    $home ||= Catalyst::Utils::home($class);

    if ($home) {
        #I remember recently being scolded for assigning config values like this
        $class->config->{home} ||= $home;
        $class->config->{root} ||= Path::Class::Dir->new($home)->subdir('root');
    }
}

=head2 $c->setup_encoding

Sets up the input/output encoding. See L<ENCODING>

=cut

sub setup_encoding {
    my $c = shift;
    if( exists($c->config->{encoding}) && !defined($c->config->{encoding}) ) {
        # Ok, so the user has explicitly said "I don't want encoding..."
        return;
    } else {
      my $enc = defined($c->config->{encoding}) ?
        delete $c->config->{encoding} : 'UTF-8'; # not sure why we delete it... (JNAP)
      $c->encoding($enc);
    }
}

=head2 handle_unicode_encoding_exception

Hook to let you customize how encoding errors are handled. By default
we just throw an exception and the default error page will pick it up.
Receives a hashref of debug information. Example of call (from the
Catalyst internals):

  my $decoded_after_fail = $c->handle_unicode_encoding_exception({
        param_value => $value,
        error_msg => $_,
        encoding_step => 'params',
   });

The calling code expects to receive a decoded string or an exception.

You can override this for custom handling of unicode errors. By
default we just die. If you want a custom response here, one approach
is to throw an HTTP style exception, instead of returning a decoded
string or throwing a generic exception.

    sub handle_unicode_encoding_exception {
      my ($c, $params) = @_;
      HTTP::Exception::BAD_REQUEST->throw(status_message=>$params->{error_msg});
    }

Alternatively you can 'catch' the error, stash it and write handling code later
in your application:

    sub handle_unicode_encoding_exception {
      my ($c, $params) = @_;
      $c->stash(BAD_UNICODE_DATA=>$params);
      # return a dummy string.
      return 1;
    }

<B>NOTE:</b> Please keep in mind that once an error like this occurs,
the request setup is still ongoing, which means the state of C<$c> and
related context parts like the request and response may not be setup
up correctly (since we haven't finished the setup yet). If you throw
an exception the setup is aborted.

=cut

sub handle_unicode_encoding_exception {
    my ( $self, $exception_ctx ) = @_;
    die $exception_ctx->{error_msg};
}

# Some unicode helpers cargo culted from the old plugin.  These could likely
# be neater.

sub _handle_unicode_decoding {
    my ( $self, $value ) = @_;

    return unless defined $value;

    ## I think this mess is to support the old nested
    if ( ref $value eq 'ARRAY' ) {
        foreach ( @$value ) {
            $_ = $self->_handle_unicode_decoding($_);
        }
        return $value;
    }
    elsif ( ref $value eq 'HASH' ) {
        foreach (keys %$value) {
            my $encoded_key = $self->_handle_param_unicode_decoding($_);
            $value->{$encoded_key} = $self->_handle_unicode_decoding($value->{$_});

            # If the key was encoded we now have two (the original and current so
            # delete the original.
            delete $value->{$_} if $_ ne $encoded_key;
        }
        return $value;
    }
    else {
        return $self->_handle_param_unicode_decoding($value);
    }
}

lib/Catalyst.pm  view on Meta::CPAN 


C<home> - The application home directory. In an uninstalled application,
this is the top level application directory. In an installed application,
this will be the directory containing C<< MyApp.pm >>.

=item *

C<ignore_frontend_proxy> - See L</PROXY SUPPORT>

=item *

C<name> - The name of the application in debug messages and the debug and
welcome screens

=item *

C<parse_on_demand> - The request body (for example file uploads) will not be parsed
until it is accessed. This allows you to (for example) check authentication (and reject
the upload) before actually receiving all the data. See L</ON-DEMAND PARSER>

=item *

C<root> - The root directory for templates. Usually this is just a
subdirectory of the home directory, but you can set it to change the
templates to a different directory.

=item *

C<search_extra> - Array reference passed to Module::Pluggable to for additional
namespaces from which components will be loaded (and constructed and stored in
C<< $c->components >>).

=item *

C<show_internal_actions> - If true, causes internal actions such as C<< _DISPATCH >>
to be shown in hit debug tables in the test server.

=item *

C<use_request_uri_for_path> - Controls if the C<REQUEST_URI> or C<PATH_INFO> environment
variable should be used for determining the request path.

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<< $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<< $c->config(use_request_uri_for_path) >> setting (which can either be true or false).

=over

=item 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 generated from a combination of the C<PATH_INFO> and C<SCRIPT_NAME> environment variables.
The allows the application to behave correctly when C<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: "C<< Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
contain path-segment parameters. >>" This means PATH_INFO is B<always> decoded, and therefore Catalyst
can't distinguish / vs %2F in paths (in addition to other encoded values).

=item use_request_uri_for_path => 1

This method uses the C<REQUEST_URI> and C<SCRIPT_NAME> environment variables. As C<REQUEST_URI> is never
decoded, this means that applications using this mode can correctly handle URIs including the %2F character
(i.e. with C<AllowEncodedSlashes> set to C<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 C<mod_rewrite>), the resolution of
C<< $c->request->base >> will be incorrect.

=back

=item *

C<using_frontend_proxy> - See L</PROXY SUPPORT>.

=item *

C<using_frontend_proxy_path> - Enabled L<Plack::Middleware::ReverseProxyPath> on your application (if
installed, otherwise log an error).  This is useful if your application is not running on the
'root' (or /) of your host server.  B<NOTE> if you use this feature you should add the required
middleware to your project dependency list since its not automatically a dependency of L<Catalyst>.
This has been done since not all people need this feature and we wish to restrict the growth of
L<Catalyst> dependencies.

=item *

C<encoding> - See L</ENCODING>

This now defaults to 'UTF-8'.  You my turn it off by setting this configuration
value to undef.

=item *

C<abort_chain_on_error_fix>

Defaults to true.

When there is an error in an action chain, the default behavior is to
abort the processing of the remaining actions to avoid running them
when the application is in an unexpected state.

Before version 5.90070, the default used to be false. To keep the old
behaviour, you can explicitly set the value to false. E.g.

    __PACKAGE__->config(abort_chain_on_error_fix => 0);

If this setting is set to false, then the remaining actions are
performed and the error is caught at the end of the chain.


=item *

C<use_hash_multivalue_in_request>

In L<Catalyst::Request> the methods C<query_parameters>, C<body_parametes>
and C<parameters> return a hashref where values might be scalar or an arrayref
depending on the incoming data.  In many cases this can be undesirable as it

lib/Catalyst.pm  view on Meta::CPAN 

This is recommended for temporary backwards compatibility only.

To turn it off for a single request use the L<clear_encoding>
method to turn off encoding for this request.  This can be useful
when you are setting the body to be an arbitrary block of bytes,
especially if that block happens to be a block of UTF8 text.

Encoding is automatically applied when the content-type is set to
a type that can be encoded.  Currently we encode when the content type
matches the following regular expression:

    $content_type =~ /^text|xml$|javascript$/

Encoding is set on the application, but it is copied to the context object
so that you can override it on a request basis.

Be default we don't automatically encode 'application/json' since the most
common approaches to generating this type of response (Either via L<Catalyst::View::JSON>
or L<Catalyst::Action::REST>) will do so already and we want to avoid double
encoding issues.

If you are producing JSON response in an unconventional manner (such
as via a template or manual strings) you should perform the UTF8 encoding
manually as well such as to conform to the JSON specification.

NOTE: We also examine the value of $c->response->content_encoding.  If
you set this (like for example 'gzip', and manually gzipping the body)
we assume that you have done all the necessary encoding yourself, since
we cannot encode the gzipped contents.  If you use a plugin like
L<Catalyst::Plugin::Compress> you need to update to a modern version in order
to have this function correctly  with the new UTF8 encoding code, or you
can use L<Plack::Middleware::Deflater> or (probably best) do your compression on
a front end proxy.

=head2 Methods

=over 4

=item encoding

Returns an instance of an C<Encode> encoding

    print $c->encoding->name

=item handle_unicode_encoding_exception ($exception_context)

Method called when decoding process for a request fails.

An C<$exception_context> hashref is provided to allow you to override the
behaviour of your application when given data with incorrect encodings.

The default method throws exceptions in the case of invalid request parameters
(resulting in a 500 error), but ignores errors in upload filenames.

The keys passed in the C<$exception_context> hash are:

=over

=item param_value

The value which was not able to be decoded.

=item error_msg

The exception received from L<Encode>.

=item encoding_step

What type of data was being decoded. Valid values are (currently)
C<params> - for request parameters / arguments / captures
and C<uploads> - for request upload filenames.

=back

=back

=head1 SUPPORT

IRC:

    Join #catalyst on irc.perl.org.

Mailing Lists:

    http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
    http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev

Web:

    http://catalyst.perl.org

Wiki:

    http://dev.catalyst.perl.org

=head1 SEE ALSO

=head2 L<Task::Catalyst> - All you need to start with Catalyst

=head2 L<Catalyst::Manual> - The Catalyst Manual

=head2 L<Catalyst::Component>, L<Catalyst::Controller> - Base classes for components

=head2 L<Catalyst::Engine> - Core engine

=head2 L<Catalyst::Log> - Log class.

=head2 L<Catalyst::Request> - Request object

=head2 L<Catalyst::Response> - Response object

=head2 L<Catalyst::Test> - The test suite.

=head1 PROJECT FOUNDER

sri: Sebastian Riedel <sri@cpan.org>

=head1 CONTRIBUTORS

abw: Andy Wardley

acme: Leon Brocard <leon@astray.com>

abraxxa: Alexander Hartmaier <abraxxa@cpan.org>

andrewalker: André Walker <andre@cpan.org>

Andrew Bramble



( run in 1.092 second using v1.01-cache-2.11-cpan-e1769b4cff6 )