The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
MIYAGAWA / Plack-Middleware-Debug-0.14 / README.mkdn

NAME

Plack::Middleware::Debug - display information about the current request/response

SYNOPSIS

# app.psgi

use Plack::Builder;

my $app = sub {
    return [ 200, [ 'Content-Type' => 'text/html' ],
           [ '<body>Hello World</body>' ] ];
};

builder {
    enable 'Debug';
    $app;
};

DESCRIPTION

The debug middleware offers a configurable set of panels that displays information about the current request and response. The information is generated only for responses with a status of 200 (OK) and a Content-Type that contains text/html and is embedded in the HTML that is sent back to the browser. Also the code is injected directly before the </body> tag so if there is no such tag, the information will not be injected.

To enable the middleware, just use Plack::Builder as usual in your .psgi file:

use Plack::Builder;

builder {
    enable 'Debug', panels => [ qw(DBITrace PerlConfig) ];
    $app;
};

The Debug middleware takes an optional panels argument whose value is expected to be a reference to an array of panel specifications. If given, only those panels will be enabled. If you don't pass a panels argument, the default list of panels - Environment, Response, Timer and Memory - will be enabled, each with their default settings.

Each panel specification can take one of three forms:

This is interpreted as the base name of a panel in the Plack::Middeware::Debug:: namespace. The panel class is loaded and a panel object is created with its default settings.

If you need to pass arguments to the panel object as it is created, use this form. The first element of the array reference has to be the panel base name. The remaining elements are key/value pairs to be passed to the panel.

Not all panels take extra arguments. But the DBITrace panel, for example, takes an optional level argument to specify the desired trace level.

For example:

builder {
    enable 'Debug', panels =>
      [ qw(Environment Response Timer Memory),
        [ 'DBITrace', level => 2 ]
      ];
    $app;
};

You can also pass panel objects directly to the Debug middleware. This might be useful if you have custom debug panels in your framework or web application.

PANELS

Display DBI trace information. See Plack::Middleware::Debug::DBITrace.

Displays the PSGI environment from the request. See Plack::Middleware::Debug::Environment.

Displays memory usage before the request and after the response. See Plack::Middleware::Debug::Memory.

Displays the loaded modules and their versions. See Plack::Middleware::Debug::ModuleVersions.

Displays the configuration information of the Perl interpreter itself. See Plack::Middleware::Debug::PerlConfig

Displays the status code and response headers. See Plack::Middleware::Debug::Response.

Displays how long the request took. See Plack::Middleware::Debug::Timer.

In a Catalyst application, this panel displays the Catalyst log output. See Plack::Middleware::Debug::CatalystLog.

HOW TO WRITE YOUR OWN DEBUG PANEL

The Debug middleware is designed to be easily extensible. You might want to write a custom debug panel for your framework or for your web application. Let's look at the anatomy of the Timer debug panel. Here is the code from that panel:

package Plack::Middleware::Debug::Timer;
use 5.008;
use strict;
use warnings;
use Time::HiRes qw(gettimeofday tv_interval);
use Plack::Util::Accessor qw(start_time elapsed);
use parent qw(Plack::Middleware::Debug::Base);
our $VERSION = '0.03';

sub nav_subtitle {
    my $self = shift;
    $self->format_elapsed;
}

sub format_elapsed {
    my $self = shift;
    sprintf '%s s', $self->elapsed;
}

sub format_time {
    my ($self, $time) = @_;
    my ($sec, $min, $hour, $mday, $mon, $year) = (localtime($time->[0]));
    sprintf "%04d.%02d.%02d %02d:%02d:%02d.%d", $year + 1900, $mon + 1, $mday,
      $hour, $min, $sec, $time->[1];
}

sub process_request {
    my ($self, $env) = @_;
    $self->start_time([gettimeofday]);
}

sub process_response {
    my ($self, $res, $env) = @_;
    my $end_time = [gettimeofday];
    $self->elapsed(tv_interval $self->start_time, $end_time);
    $self->content(
        $self->render_list_pairs(
            [   Start   => $self->format_time($self->start_time),
                End     => $self->format_time($end_time),
                Elapsed => $self->format_elapsed,
            ]
        )
    );
}

To write a new debug panel, place it in the Plack::Middleware::Debug:: namespace. In our example, the Timer panel lives in the Plack::Middleware::Debug::Timer package.

A panel should subclass Plack::Middleware::Debug::Base. It provides a lot of methods that the Debug middleware expects a panel to have and provides some sensible defaults for others, so you only need to override what is specific to your custom panel.

The panels' title - which appears at the top left when the panel is active - and its navigation title - which appears in the navigation bar on the right side - are set automatically from the panel's base name - Timer in our case. This is a useful for default for us, so we don't need to override these methods.

The panels' navigation subtitle, which appears in the navigation bar underneath the panel title in smaller letters, is empty by default. For the Timer panel, we would like to show the total time elapsed so the user can get the quick overview without having to activate the panel. So we override the nav_subtitle() method.

How do we know how much time elapsed for the request? We have to take the time when the request comes in, and again when the response goes out. So we override the process_request() and process_response() methods. In process_request() we just store the current time. To generate the accessors for any attributes our panel might need we use Plack::Util::Accessor.

In process_response() we take the time again, determine how much time has elapsed, store that information in an accessor so sub_navtitle() can return it when asked by the template, then we actually render the template with our data and store it in content().

When the HTML, CSS and JavaScript are generated and injected by the Debug middleware, it will ask all panels whether they have any content. If so, the actual panel is generated. If not, then just an inactive navigation bar entry is generated. Having data in the panel's content attribute is the sign that the Debug middleware looks for.

In our Timer example we want to list three key/value pairs: the start time, the end time and the elapsed time. We use the render_list_pairs() method to place the pairs in the order we want. There is also a render_hash() method, but it would sort the hash keys, and this is not what we want.

With this our Timer debug panel is finished. Now we can use it in the enable 'Debug' call like any other debug panel.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through the web interface at http://rt.cpan.org.

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

AVAILABILITY

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit http://www.perl.com/CPAN/ to find a CPAN site near you. Or see http://search.cpan.org/dist/Plack-Middleware-Debug/.

The development version lives at http://github.com/hanekomu/plack-middleware-debug/. Instead of sending patches, please fork this project using the standard git and github infrastructure.

AUTHORS

Marcel Grünauer, <marcel@cpan.org>

Tatsuhiko Miyagawa, <miyagawa@bulknews.net>

COPYRIGHT AND LICENSE

Copyright 2009 by Marcel Grünauer

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

The debug middleware is heavily influenced (that is, adapted from) the Django Debug Toolbar - see http://github.com/robhudson/django-debug-toolbar.