NAME

Mojolicious::Plugin::ErrorsAndWarnings - Store errors & warnings during a request

SYNOPSIS

  # Mojolicious example
  package MyApp;
  use Mojo::Base 'Mojolicious';

  sub startup {
    my $self = shift;

    $self->plugin('ErrorsAndWarnings');

    # Router
    my $r = $self->routes;
    $r->get('/')->to(cb => sub {
      my $c = shift;
      $c->add_error('first_error');
      $c->add_error('second_error', more => 'detail');

      # {"errors":[{"code":"first_error"},{"code":"second_error","more":"detail"}]}
      $c->render(json => { errors => $c->errors });
    });
  }

  1;

DESCRIPTION

Mojolicious::Plugin::ErrorsAndWarnings is a basic plugin for Mojolicious which provides helpers to store and retrieve user-defined errors and warnings. This is particularly useful to help collect errors and warnings from within multiple method calls during a request cycle. At the end of the request, the error and warning objects provide additional information about any problems encountered while performing an operation.

Adding errors or warnings will store them under the Mojolicious stash key plugin.errors by default. Don't access this stash value directly. Use the $c->errors and $c->warnings accessors instead.

  # add errors and warnings using the imported helpers
  $c->add_error('first_error');
  $c->add_warning('first_warning');

  # {"errors":[{"code":"first_error"}], "warnings":[{"code":"first_warning"}]}
  $c->render(json => {errors => $c->errors, warnings => $c->warnings});

The first argument to "add_error" or "add_warning" is referred to as the code. This an application-specific error or warning code, expressed as a string value.

  $c->add_error('sql', status => 400, title => 'Your SQL is malformed.');
  $c->add_warning('search', title => 'Invalid search column.', path => 'pw');

  # {
  #    "errors": [
  #        {
  #            "code": "sql",
  #            "status": 400,
  #            "title": "Your SQL is malformed."
  #        }
  #    ],
  #    "warnings": [
  #        {
  #            "code": "search",
  #            "path": "password",
  #            "title": "Invalid search column."
  #        }
  #    ]
  # }
  $c->render(json => {errors => $c->errors, warnings => $c->warnings});

Additional members can be added to provide more specific information about the problem. See also http://jsonapi.org/format/#errors for examples of other members you might want to use.

ATTRIBUTES

Mojolicious::Plugin::ErrorsAndWarnings implements the following attributes.

config_key

The name of the config key to inspect for user-defined error and warning codes. Defaults to codes.

The plugin will merge default values from an app's config if a matching key is found. See the example below.

  # Mojolicious::Lite example merging config values
  use Mojolicious::Lite;

  plugin 'ErrorsAndWarnings';

  app->config({
    # config_key attribute is `codes' by default
    codes => {
      # Default key/values merged for unmatched code names
      'default'            => {status => 400},

      # Global codes
      'forbidden'          => {status => 403, title => 'Permission denied to resource.'},
      'not_found'          => {status => 404, title => 'Not found.'},
      'method_not_allowed' => {status => 405, title => 'Method not allowed.'},
    },
  });

  get '/' => sub {
    my $c = shift;

    $c->add_error('not_found');
    $c->add_error('user_defined_err', foo => 'bar bar' );

    # {
    #    "errors": [
    #        {
    #            "code": "not_found",
    #            "status": 404,
    #            "title": "Not found."
    #        },
    #        {
    #            "code": "user_defined_err",
    #            "status": 400,
    #            "foo": "bar bar"
    #        }
    #    ]
    # }
    $c->render(json => { errors => $c->errors });
  };

stash_key

Name of the Mojolicious stash key to store the errors and warnings. Defaults to plugin.errors.

Don't access this stash value directly. Use the $c->errors and $c->warnings accessors instead.

HELPERS

Mojolicious::Plugin::ErrorsAndWarnings implements the following helpers.

add_error

  $self->add_error('user_not_found');
  $self->add_error('user_not_found', additional => 'Error Attr');
  $self->add_error('user_not_found', code => 'rename_error_code');

Pushes to the errors stash.

add_warning

  $self->add_warning('field_ignored');
  $self->add_warning('field_ignored', path => 'username');
  $self->add_warning('field_ignored', code => 'rename_warning_code');

Pushes to the warnings stash.

errors

Returns an ARRAYREF of errors.

warnings

Returns an ARRAYREF of warnings.

METHODS

Mojolicious::Plugin::Config inherits all methods from Mojolicious::Plugin and implements the following new ones.

register

  $plugin->register(Mojolicious->new);

Register plugin in Mojolicious application.

COPYRIGHT AND LICENSE

Copyright (C) 2015, Paul Williams.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

AUTHOR

Paul Williams <kwakwa@cpan.org>

SEE ALSO

Mojolicious, Mojolicious::Guides, http://mojolicio.us.

cpanm Mojolicious::Plugin::ErrorsAndWarnings

perl -MCPAN -e shell
install Mojolicious::Plugin::ErrorsAndWarnings