NAME

Catalyst::Plugin::Errors - Standard error responses with content negotiation

SYNOPSIS

Use in your application class

    package Example;

    use Catalyst;

    __PACKAGE__->setup_plugins([qw/Errors/]);
    __PACKAGE__->setup();
    __PACKAGE__->meta->make_immutable();

And then you can use it in a controller (or anyplace where you have $c context).

    package Example::Controller::Root;

    use Moose;
    use MooseX::MethodAttributes;

    extends 'Catalyst::Controller';

    sub root :Chained(/) PathPart('') CaptureArgs(0) {} 

      sub not_found :Chained(root) PathPart('') Args {
        my ($self, $c, @args) = @_;
        $c->detach_error(404);
      }

    __PACKAGE__->config(namespace=>'');
    __PACKAGE__->meta->make_immutable;

DESCRIPTION

This is a plugin which installs (if needed) View classes to handle HTTP errors (4xx and 5xx codes) in a regular and content negotiated way. See <CatalystX::Errors> for a high level overview. Documentation here is more API level and the examples are sparse.

METHODS

This plugin adds the following methods to your $c context.

dispatch_error ($code, ?\@additional_headers, ?\%template_args)

Examples:

    $c->detach_error(404);
    $c->detach_error(404, +{error=>'invalid uri request'});
    $c->detach_error(401, ['WWW-Authenticate" => 'Basic realm=myapp, charset="UTF-8"'], +{error=>'unauthorized access attempt'});

Dispatches to an error view based on content negotiation and the provided code. You can also pass an arrayref of extra HTTP headers (such as www-authenticate for 401 errors) and also optionally a hashref of fields that will be sent to the view.

When dispatching to a $view we use the following rules in order:

First if the View has a method http_${code} (where $code is the HTTP status code you are using for the error) we call that method with args $c, %template_args and expect that method to setup a valid error response.

Second, call the method http_default with args $c, $code, %template_args if that exists.

If neither method exists we call $c-forward($view)> and %template_args are added to the stash, along with a stash var 'template' which is set to 'http_error'. This should work with most standard Catalyst views that look at the stash field 'template' to find a template name. If you prefer a different template name you can override the method 'generate_error_template_name' to make it whatever you wish.

NOTE Using dispatch_error (or detach_error) doesn't add anything to the Catalyst error log as we consider this control flow more than anything else. If you want to log a special line you can add an error field to %template_args and that we go to the error log.

detach_error

Calls "dispatch_error" with the provided arguments and then does a $c-detach> which effectively ends processing for the action.

CONFIGURATION & CUSTOMIZATION

This plugin can be customized with the following configuration options or via overriding or adapting the following methods

finalize_error_args

This method provides the actual arguments given to the error view (args which are for example used in the template for messaging to the end user). You can override this to provide your own version. See the source for how this should work

Configuration keys

This plugin defines the following configuration by default, which you can override.

    package Example;

    use Catalyst;

    __PACKAGE__->setup_plugins([qw/Errors/]);
    __PACKAGE__->config(
      # This is the configuration which is default.  You don't have to actually type
      # this out.  I'm just putting it here to show you what its doing under the hood.
      'Plugin::Errors' => +{
        default_media_type => 'text/plain',
        default_language => 'en_US',
        views => +{
          'text/html'   => 'Errors::HTML',
          'text/plain'  => 'Errors::Text',
          'application/json' => 'Errors::JSON',
        },
      },
    );

    __PACKAGE__->setup();
    __PACKAGE__->meta->make_immutable();

By default we map the media types text/html, text/plain and application/json to cooresponding views. This views are injected automatically if you don't provide subclasses or your own view locally. The following views are injected as needed:

Catalyst::View::Error::HTML, Catalyst::View::Error::Text, and .

You can check the docs for each of the default views for customization options but you can always make a local subclass inside you application's view directory and tweak as desired (or you can just use your own view or one of the common ones on CPAN).

You can also add additional media types mappings.

SEE ALSO

CatalystX::Errors.

AUTHOR

CatalystX::Errors.

COPYRIGHT & LICENSE

CatalystX::Errors.

cpanm CatalystX::Errors

perl -MCPAN -e shell
install CatalystX::Errors