Debian Codegraph @

README

raw
1 NAME
2
3 Plack::Middleware::Debug - display information about the current
4 request/response
5
6 SYNOPSIS
7
8 enable "Debug";
9
10 DESCRIPTION
11
12 The debug middleware offers a configurable set of panels that displays
13 information about the current request and response. The information is
14 generated only for responses with a status of 200 (OK) and a
15 Content-Type that contains text/html or application/xhtml+xml and is
16 embedded in the HTML that is sent back to the browser.
17
18 Note that the code is injected directly before the closing tag
19 (</body>) so if there is no such tag, the debug panel will not be
20 injected at all.
21
22 To enable the middleware, just use Plack::Builder as usual in your
23 .psgi file:
24
25 use Plack::Builder;
26
27 builder {
28 enable 'Debug', panels => [ qw(DBITrace Memory Timer) ];
29 $app;
30 };
31
32 The Debug middleware takes an optional panels argument whose value is
33 expected to be a reference to an array of panel specifications. If
34 given, only those panels will be enabled. If you don't pass a panels
35 argument, the default list of panels - Environment, Response, Timer,
36 Memory, Session and DBITrace - will be enabled, each with their default
37 settings, and automatically disabled if their target modules or
38 middleware components are not loaded.
39
40 Each panel specification can take one of three forms:
41
42 A string
43
44 This is interpreted as the base name of a panel in the
45 Plack::Middeware::Debug:: namespace, unless preceded by +, in which
46 case it's interpreted as an absolute name similar to how
47 Plack::Builder handles such names, e.g.
48 +My::Plack::Middleware::Debug::Something.
49
50 The panel class is loaded and a panel object is created with its
51 default settings.
52
53 An array reference
54
55 If you need to pass arguments to the panel object as it is created,
56 you may use this form (But see below).
57
58 The first element of the array reference has to be the panel base
59 name. The remaining elements are key/value pairs to be passed to the
60 panel.
61
62 For example:
63
64 builder {
65 enable 'Debug', panels =>
66 [ qw(Environment Response Timer Memory),
67 [ 'DBITrace', level => 2 ]
68 ];
69 $app;
70 };
71
72 Because each panel is a middleware component, you can write this way
73 as well:
74
75 builder {
76 enable 'Debug'; # load defaults
77 enable 'Debug::DBITrace', level => 2;
78 $app;
79 };
80
81 Note that the <enable 'Debug'> line should come before other Debug
82 panels because of the order middleware components are executed.
83
84 Custom middleware
85
86 You can also pass a Panel middleware component. This might be useful
87 if you have custom debug panels in your framework or web application.
88
89 HOW TO WRITE YOUR OWN DEBUG PANEL
90
91 The Debug middleware is designed to be easily extensible. You might
92 want to write a custom debug panel for your framework or for your web
93 application. Each debug panel is also a Plack middleware component and
94 is easy to write one.
95
96 Let's look at the anatomy of the Timer debug panel. Here is the code
97 from that panel:
98
99 package Plack::Middleware::Debug::Timer;
100 use Time::HiRes;
101
102 use parent qw(Plack::Middleware::Debug::Base);
103
104 sub run {
105 my($self, $env, $panel) = @_;
106
107 my $start = [ Time::HiRes::gettimeofday ];
108
109 return sub {
110 my $res = shift;
111
112 my $end = [ Time::HiRes::gettimeofday ];
113 my $elapsed = sprintf '%.6f s', Time::HiRes::tv_interval $start, $end;
114
115 $panel->nav_subtitle($elapsed);
116 $panel->content(
117 $self->render_list_pairs(
118 [ Start => $self->format_time($start),
119 End => $self->format_time($end),
120 Elapsed => $elapsed ],
121 ),
122 );
123 };
124 }
125
126 sub format_time { ... }
127
128 To write a new debug panel, place it in the Plack::Middleware::Debug::
129 namespace. In our example, the Timer panel lives in the
130 Plack::Middleware::Debug::Timer package.
131
132 The only thing your panel should do is to subclass
133 Plack::Middleware::Debug::Base. This does most of the things a
134 middleware component should do as a Plack middleware, so you only need
135 to override run method to profile and create the panel content.
136
137 sub run {
138 my($self, $env, $panel) = @_;
139
140 # Do something before the application runs
141
142 return sub {
143 my $res = shift;
144
145 # Do something after the application returns
146
147 };
148 }
149
150 You can create as many lexical variables as you need and reference that
151 in the returned callback as a closure, and update the content of of the
152 $panel which is Plack::Middleware::Debug::Panel object.
153
154 In our Timer example we want to list three key/value pairs: the start
155 time, the end time and the elapsed time. We use the render_list_pairs()
156 method to place the pairs in the order we want. There is also a
157 render_hash() and render_lines() method, to render a hash keys and
158 values, as well as just text lines (e.g. log messages).
159
160 BUGS AND LIMITATIONS
161
162 Please report any bugs or feature requests through the web interface at
163 http://rt.cpan.org.
164
165 INSTALLATION
166
167 See perlmodinstall for information and options on installing Perl
168 modules.
169
170 AVAILABILITY
171
172 The latest version of this module is available from the Comprehensive
173 Perl Archive Network (CPAN). Visit http://www.perl.com/CPAN/ to find a
174 CPAN site near you. Or see
175 http://search.cpan.org/dist/Plack-Middleware-Debug/.
176
177 The development version lives at
178 http://github.com/miyagawa/plack-middleware-debug/. Instead of sending
179 patches, please fork this project using the standard git and github
180 infrastructure.
181
182 AUTHORS
183
184 Marcel Grunauer, <[email protected]>
185
186 Tatsuhiko Miyagawa, <[email protected]>
187
188 COPYRIGHT AND LICENSE
189
190 Copyright 2009 by Marcel GrĂ¼nauer
191
192 This library is free software; you can redistribute it and/or modify it
193 under the same terms as Perl itself.
194
195 SEE ALSO
196
197 The debug middleware is heavily influenced (that is, adapted from) the
198 Django Debug Toolbar - see
199 http://github.com/robhudson/django-debug-toolbar.
200