| 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 |
|