# NAME Catalyst::Plugin::ErrorCatcher - Catch application errors and emit them somewhere # VERSION version 0.0.8.20 # 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: enable 1 context 5 always_log 0 include_session 0 user_identified_by username emit_module A::Module - **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: enable 1 enable 1 # include other options here 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 # 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 - Fitz Elliott - Mohammad S Anwar - Tim Bunce