Plack:...:Debug(3pm)

💖 Plack::Middleware::Debug — the manual page but make it a group chat 💖

okay bestie, come sit, we're doing Plack:...:Debug(3pm) from User Contributed Perl Documentation and it's genuinely so useful. it's giving "I want to see what my app is doing in the browser, live." ✨

---

✨ NAME ✨

Plack::Middleware::Debug — it shows you info about the current request/response. that's the whole vibe. 💅

---

✨ SYNOPSIS ✨

enable "Debug";

one line. that's it. iconic. 🎀

---

✨ DESCRIPTION ✨

so the deal is: this debug middleware gives you a configurable set of panels, and those panels display info about the current request and response. very main character energy.

BUT — and this is important, no cap — the info is only generated for responses that have both of these going on:

• status 200 ("OK"), and
• a Content-Type that contains text/html or application/xhtml+xml.

and then it gets embedded in the HTML that's sent back to the browser. 🦋

⚠️ heads up: the code is injected directly before the closing tag (</body>). so if there's no such tag?? the debug panel just... doesn't get injected at all. literally nowhere. it's giving shy. 😭

to actually turn the middleware on, you just use Plack::Builder like you normally would in your .psgi file:

use Plack::Builder;

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

the Debug middleware takes an optional panels argument, and its value is expected to be a reference to an array of panel specifications. if you pass it, only those panels get enabled. if you don't pass a panels argument, you get the default list of panels — Environment, Response, Timer, Memory, Session and DBITrace — each with their default settings, and each one is automatically disabled if its target modules or middleware components aren't loaded. love a self-aware queen. 👑

each panel specification can take one of three forms:

🌸 A string

this gets interpreted as the base name of a panel in the Plack::Middeware::Debug:: namespace... unless it's preceded by +, in which case it's interpreted as an absolute name, similar to how Plack::Builder handles such names. for example:

+My::Plack::Middleware::Debug::Something

the panel class is loaded and a panel object is created with its default settings. simple. slay. ✨

🌸 An array reference

if you need to pass arguments to the panel object as it's created, you can use this form (but see below 👀).

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.

for example:

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

and here's the thing: because each panel is a middleware component, you can also write it this way instead:

builder {
    enable 'Debug'; # load defaults
    enable 'Debug::DBITrace', level => 2;
    $app;
};

🫶 small but crucial note: the enable 'Debug' line should come before the other Debug panels, because of the order middleware components are executed. order matters bestie, always has. 💅

🌸 Custom middleware

you can also just pass a Panel middleware component directly. this might be useful if you have custom debug panels in your framework or web application. yes, you can be that girl. 👑

---

✨ 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. every debug panel is also a Plack middleware component, and writing one is easy. 🧚

let's look at the anatomy of the Timer debug panel. here's the code from that panel:

package Plack::Middleware::Debug::Timer;
use Time::HiRes;

use parent qw(Plack::Middleware::Debug::Base);

sub run {
    my($self, $env, $panel) = @_;

    my $start = [ Time::HiRes::gettimeofday ];

    return sub {
        my $res = shift;

        my $end = [ Time::HiRes::gettimeofday ];
        my $elapsed = sprintf '%.6f s', Time::HiRes::tv_interval $start, $end;

        $panel->nav_subtitle($elapsed);
        $panel->content(
            $self->render_list_pairs(
                [ Start  => $self->format_time($start),
                  End    => $self->format_time($end),
                  Elapsed => $elapsed ],
            ),
        );
    };
}

sub format_time { ... }

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

the only thing your panel should do is subclass Plack::Middleware::Debug::Base. that base class does most of the things a middleware component should do as a Plack middleware, so all you actually need to override is the run method — that's what profiles and creates the panel content:

sub run {
    my($self, $env, $panel) = @_;

    # Do something before the application runs

    return sub {
        my $res = shift;

        # Do something after the application returns

    };
}

you can create as many lexical variables as you need, reference them inside that returned callback as a closure, and update the content of the $panel, which is a Plack::Middleware::Debug::Panel object. 💜

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's also a render_hash() and a render_lines() method, to render hash keys and values, as well as just plain text lines (e.g. log messages). obsessed. 🔥

---

✨ BUGS AND LIMITATIONS ✨

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/miyagawa/plack-middleware-debug/>. and listen — instead of sending patches, please fork this project using the standard git and github infrastructure. bestie that's the way. 🧚

---

✨ AUTHORS ✨

• Marcel Grunauer, <marcel@cpan.org>
• Tatsuhiko Miyagawa, <miyagawa@bulknews.net>

two icons. we stan. 👑

---

✨ COPYRIGHT AND LICENSE ✨

Copyright 2009 by Marcel Gruenauer

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

---

and that's the whole page, bestie!! 🌸 this version came to you courtesy of perl v5.36.0, dated 2022-10-14 — go forth and debug your little heart out. periodt. 💅✨🎀