# NAME

Catalyst::Plugin::ErrorCatcher - Catch application errors and emit them somewhere

# VERSION

version 0.0.8.21

# SYNOPSIS

   use Catalyst qw/-Debug StackTrace ErrorCatcher/;

# DESCRIPTION

This plugin allows you to do More Stuff with the information that would
normally only be seen on the Catalyst Error Screen courtesy of the
[Catalyst::Plugin::StackTrace](https://metacpan.org/pod/Catalyst::Plugin::StackTrace) plugin.

## setup($c, $@)

Prepare the plugin for use.

## finalize\_error($c)

If configured, and needed, deal with raised errors.

## my\_finalize\_error($c)

This is the method that's called by `finalize_error` when we do want to use ErrorCatcher
to format and emit some information.

## emitters\_init($c)

This routine initialises the emitters enabled in the configuration for the plugin.

## append\_feedback($stringref, $data)

This is a small utility method that simplifies some of the work needed to
add some data to a string-reference, including some basic checks and initialisation.

## append\_feedback\_emptyline

Add an empty-line to the string-reference of data being built.

## append\_feedback\_keyvalue($ref, $key, $value, $keypadding)

Add:

   {key}: value

to the feedback data being prepared.

`$keypadding` is optional. If omitted, defaults to 8.

## sanitise\_param($value)

Local implementation of ["qquote" in Data::Dumper](https://metacpan.org/pod/Data::Dumper#qquote) and general sanity checks and
transformations of the data in a given piece of data.

## append\_output\_params($ref, $label, $params)

Given a hashref of related items, `$params`, and a `$label` for the grouping,
add sensibly formatted output to the feedback data being constructed.

# CONFIGURATION

The plugin is configured in a similar manner to other Catalyst plugins:

   <Plugin::ErrorCatcher>
       enable                1
       context               5
       always_log            0
       include_session       0
       user_identified_by    username

       emit_module           A::Module
   </Plugin::ErrorCatcher>

- **enable**

   Setting this to _true_ forces the module to work its voodoo.

   It's also enabled if the value is unset and you're running Catalyst in
   debug-mode.

- **context**

   When there is stack-trace information to share, how many lines of context to
   show around the line that caused the error.

- **emit\_module**

   This specifies which module to use for custom output behaviour.

   You can chain multiple modules by specifying a line in the config for each
   module you'd like used:

       emit_module A::Module
       emit_module Another::Module
       emit_module Yet::Another::Module

   If none are specified, or all that are specified fail, the default behaviour
   is to log the prepared message at the INFO level via `$c->log()`.

   For details on how to implement a custom emitter see ["CUSTOM EMIT CLASSES"](#custom-emit-classes)
   in this documentation.

- **always\_log**

   The default plugin behaviour when using one or more emitter modules is to
   suppress the _info_ log message if one or more of them succeeded.

   If you wish to log the information, via `$c->log()` then set this value
   to 1.

- **include\_session**

   The default behaviour is to suppress potentially sensitive and revealing
   session-data in the error report.

   If you feel that this information is useful in your investigations set the
   value to _true_.

   When set to 1 the report will include a `Data::Dump::pp()` representation of
   the request's session.

- **user\_identified\_by**

   If there's a logged-in user use the specified value as the method to identify
   the user.

   If the specified value is invalid the module defaults to using _id_.

   If unspecified the value defaults to _id_.

# STACKTRACE IN REPORTS WHEN NOT RUNNING IN DEBUG MODE

It is possible to run your application in non-Debug mode, and still have
errors reported with a stack-trace.

Include the StackTrace and ErrorCatcher plugins in MyApp.pm:

   use Catalyst qw<
     ErrorCatcher
     StackTrace
   >;

Set up your `myapp.conf` to include the following:

   <stacktrace>
     enable      1
   </stacktrace>

   <Plugin::ErrorCatcher>
     enable      1
     # include other options here
   <Plugin::ErrorCatcher>

Any exceptions should now show your user the _"Please come back later"_
screen whilst still capturing and emitting a report with stack-trace.

# PROVIDED EMIT CLASSES

## Catalyst::Plugin::ErrorCatcher::Email

This module uses [MIME::Lite](https://metacpan.org/pod/MIME::Lite) to send the prepared output to a specified
email address.

See [Catalyst::Plugin::ErrorCatcher::Email](https://metacpan.org/pod/Catalyst::Plugin::ErrorCatcher::Email) for usage and configuration
details.

# CUSTOM EMIT CLASSES

A custom emit class takes the following format:

   package A::Module;
   # vim: ts=8 sts=4 et sw=4 sr sta
   use strict;
   use warnings;

   sub emit {
     my ($class, $c, $output) = @_;

     $c->log->info(
       'IGNORING OUTPUT FROM Catalyst::Plugin::ErrorCatcher'
     );

     return;
   }

   1;
   __END__

The only requirement is that you have a sub called `emit`.

`Catalyst::Plugin::ErrorCatcher` passes the following parameters in the call
to `emit()`:

- **$class**

   The package name

- **$c**

   A [Context](https://metacpan.org/pod/Catalyst::Manual::Intro#Context) object

- **$output**

   The processed output from `Catalyst::Plugin::ErrorCatcher`

If you want to use the original error message you should use:

   my @error = @{ $c->error };

You may use and abuse any Catalyst methods, or other Perl modules as you see
fit.

# KNOWN ISSUES

- BODY tests failing (Catalyst >=5.90008)

   Summary: https://github.com/chiselwright/catalyst-plugin-errorcatcher/pull/1

   Bug report: https://rt.cpan.org/Public/Bug/Display.html?id=75607

# SEE ALSO

[Catalyst](https://metacpan.org/pod/Catalyst),
[Catalyst::Plugin::StackTrace](https://metacpan.org/pod/Catalyst::Plugin::StackTrace)

# THANKS

The authors of [Catalyst::Plugin::StackTrace](https://metacpan.org/pod/Catalyst::Plugin::StackTrace), from which a lot of
code was used.

Ash Berlin for guiding me in the right direction after a known hacky first
implementation.

\# vim: ts=8 sts=4 et sw=4 sr sta

# AUTHOR

Chisel <[email protected]>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Chisel Wright.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

# CONTRIBUTORS

- Chisel Wright <[email protected]>
- Fitz Elliott <[email protected]>
- Mohammad S Anwar <[email protected]>
- Tim Bunce <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.