README.mkdn
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