1# NAME
2
3Catalyst::Plugin::ErrorCatcher - Catch application errors and emit them somewhere
4
5# VERSION
6
7version 0.0.8.21
8
9# SYNOPSIS
10
11    use Catalyst qw/-Debug StackTrace ErrorCatcher/;
12
13# DESCRIPTION
14
15This plugin allows you to do More Stuff with the information that would
16normally only be seen on the Catalyst Error Screen courtesy of the
17[Catalyst::Plugin::StackTrace](https://metacpan.org/pod/Catalyst::Plugin::StackTrace) plugin.
18
19## setup($c, $@)
20
21Prepare the plugin for use.
22
23## finalize\_error($c)
24
25If configured, and needed, deal with raised errors.
26
27## my\_finalize\_error($c)
28
29This is the method that's called by `finalize_error` when we do want to use ErrorCatcher
30to format and emit some information.
31
32## emitters\_init($c)
33
34This routine initialises the emitters enabled in the configuration for the plugin.
35
36## append\_feedback($stringref, $data)
37
38This is a small utility method that simplifies some of the work needed to
39add some data to a string-reference, including some basic checks and initialisation.
40
41## append\_feedback\_emptyline
42
43Add an empty-line to the string-reference of data being built.
44
45## append\_feedback\_keyvalue($ref, $key, $value, $keypadding)
46
47Add:
48
49    {key}: value
50
51to the feedback data being prepared.
52
53`$keypadding` is optional. If omitted, defaults to 8.
54
55## sanitise\_param($value)
56
57Local implementation of ["qquote" in Data::Dumper](https://metacpan.org/pod/Data::Dumper#qquote) and general sanity checks and
58transformations of the data in a given piece of data.
59
60## append\_output\_params($ref, $label, $params)
61
62Given a hashref of related items, `$params`, and a `$label` for the grouping,
63add sensibly formatted output to the feedback data being constructed.
64
65# CONFIGURATION
66
67The plugin is configured in a similar manner to other Catalyst plugins:
68
69    <Plugin::ErrorCatcher>
70        enable                1
71        context               5
72        always_log            0
73        include_session       0
74        user_identified_by    username
75
76        emit_module           A::Module
77    </Plugin::ErrorCatcher>
78
79- **enable**
80
81    Setting this to _true_ forces the module to work its voodoo.
82
83    It's also enabled if the value is unset and you're running Catalyst in
84    debug-mode.
85
86- **context**
87
88    When there is stack-trace information to share, how many lines of context to
89    show around the line that caused the error.
90
91- **emit\_module**
92
93    This specifies which module to use for custom output behaviour.
94
95    You can chain multiple modules by specifying a line in the config for each
96    module you'd like used:
97
98        emit_module A::Module
99        emit_module Another::Module
100        emit_module Yet::Another::Module
101
102    If none are specified, or all that are specified fail, the default behaviour
103    is to log the prepared message at the INFO level via `$c->log()`.
104
105    For details on how to implement a custom emitter see ["CUSTOM EMIT CLASSES"](#custom-emit-classes)
106    in this documentation.
107
108- **always\_log**
109
110    The default plugin behaviour when using one or more emitter modules is to
111    suppress the _info_ log message if one or more of them succeeded.
112
113    If you wish to log the information, via `$c->log()` then set this value
114    to 1.
115
116- **include\_session**
117
118    The default behaviour is to suppress potentially sensitive and revealing
119    session-data in the error report.
120
121    If you feel that this information is useful in your investigations set the
122    value to _true_.
123
124    When set to 1 the report will include a `Data::Dump::pp()` representation of
125    the request's session.
126
127- **user\_identified\_by**
128
129    If there's a logged-in user use the specified value as the method to identify
130    the user.
131
132    If the specified value is invalid the module defaults to using _id_.
133
134    If unspecified the value defaults to _id_.
135
136# STACKTRACE IN REPORTS WHEN NOT RUNNING IN DEBUG MODE
137
138It is possible to run your application in non-Debug mode, and still have
139errors reported with a stack-trace.
140
141Include the StackTrace and ErrorCatcher plugins in MyApp.pm:
142
143    use Catalyst qw<
144      ErrorCatcher
145      StackTrace
146    >;
147
148Set up your `myapp.conf` to include the following:
149
150    <stacktrace>
151      enable      1
152    </stacktrace>
153
154    <Plugin::ErrorCatcher>
155      enable      1
156      # include other options here
157    <Plugin::ErrorCatcher>
158
159Any exceptions should now show your user the _"Please come back later"_
160screen whilst still capturing and emitting a report with stack-trace.
161
162# PROVIDED EMIT CLASSES
163
164## Catalyst::Plugin::ErrorCatcher::Email
165
166This module uses [MIME::Lite](https://metacpan.org/pod/MIME::Lite) to send the prepared output to a specified
167email address.
168
169See [Catalyst::Plugin::ErrorCatcher::Email](https://metacpan.org/pod/Catalyst::Plugin::ErrorCatcher::Email) for usage and configuration
170details.
171
172# CUSTOM EMIT CLASSES
173
174A custom emit class takes the following format:
175
176    package A::Module;
177    # vim: ts=8 sts=4 et sw=4 sr sta
178    use strict;
179    use warnings;
180
181    sub emit {
182      my ($class, $c, $output) = @_;
183
184      $c->log->info(
185        'IGNORING OUTPUT FROM Catalyst::Plugin::ErrorCatcher'
186      );
187
188      return;
189    }
190
191    1;
192    __END__
193
194The only requirement is that you have a sub called `emit`.
195
196`Catalyst::Plugin::ErrorCatcher` passes the following parameters in the call
197to `emit()`:
198
199- **$class**
200
201    The package name
202
203- **$c**
204
205    A [Context](https://metacpan.org/pod/Catalyst::Manual::Intro#Context) object
206
207- **$output**
208
209    The processed output from `Catalyst::Plugin::ErrorCatcher`
210
211If you want to use the original error message you should use:
212
213    my @error = @{ $c->error };
214
215You may use and abuse any Catalyst methods, or other Perl modules as you see
216fit.
217
218# KNOWN ISSUES
219
220- BODY tests failing (Catalyst >=5.90008)
221
222    Summary: https://github.com/chiselwright/catalyst-plugin-errorcatcher/pull/1
223
224    Bug report: https://rt.cpan.org/Public/Bug/Display.html?id=75607
225
226# SEE ALSO
227
228[Catalyst](https://metacpan.org/pod/Catalyst),
229[Catalyst::Plugin::StackTrace](https://metacpan.org/pod/Catalyst::Plugin::StackTrace)
230
231# THANKS
232
233The authors of [Catalyst::Plugin::StackTrace](https://metacpan.org/pod/Catalyst::Plugin::StackTrace), from which a lot of
234code was used.
235
236Ash Berlin for guiding me in the right direction after a known hacky first
237implementation.
238
239\# vim: ts=8 sts=4 et sw=4 sr sta
240
241# AUTHOR
242
243Chisel <chisel@chizography.net>
244
245# COPYRIGHT AND LICENSE
246
247This software is copyright (c) 2015 by Chisel Wright.
248
249This is free software; you can redistribute it and/or modify it under
250the same terms as the Perl 5 programming language system itself.
251
252# CONTRIBUTORS
253
254- Chisel Wright <chisel@chizography.net>
255- Fitz Elliott <fitz.elliott@gmail.com>
256- Mohammad S Anwar <mohammad.anwar@yahoo.com>
257- Tim Bunce <tim@tigerlms.com>
258