NAME

Plack::Middleware::DBGp - interactive debugging for Plack applications

SYNOPSIS

    # should be the first/one of the first modules to be loaded
    use Plack::Middleware::DBGp (
        remote_host => "localhost:9000",
    );
    use Plack::Builder;

    builder {
        enable "DBGp";
        $app;
    };

DESCRIPTION

Add interactive debugging support via the DBGp protocol to Plack applications.

When debugging, the debugger running inside the application establishes a connection to an external DBGp client (typically a GUI program) that allows to inspect the program state from the outside.

Plack::Middleware::DBGp has been tested with This implementation has been tested with pugdebug, Sublime Text Xdebug plugin and Vim VDebug plugin.

LOADING

The Perl debugger needs to be enabled early during compilation, therefore this middleware needs to be loaded explicitly near the top of the main .psgi file of the application. All files loaded before the debugger won't be debuggable (unless Enbugger is present and enabled).

Supported parameters

remote_host

    use Plack::Middleware::DBGp (
        remote_host => "host:port",
    );

Hostname/port the debugger should connect to.

user, client_dir, client_socket

    use Plack::Middleware::DBGp (
        user            => 'Unix login',
        client_dir      => '/path/to/dir',
        client_socket   => '/path/to/dir/and_socket',
    );

Unix-domain socket the debugger should connect to. The directory must be present, must be owned by the specified user and the group under which the web server is running, and it must not be world-readable/writable.

The user and client_dir parameters are optional, and used for extra sanity checks.

autostart

    use Plack::Middleware::DBGp (
        autostart   => [0|1],
    );

Whether the debugger should try connect to the debugger client on every request; see also "HTTP INTERFACE".

ide_key

    use Plack::Middleware::DBGp (
        ide_key     => "DBGp ide key",
    );

The IDE key, as defined by the DBGp protocol. Only used when autostart is in effect.

cookie_expiration

    use Plack::Middleware::DBGp (
        cookie_expiration   => <seconds>,
    );

XDEBUG_SESSION cookie expiration time, in seconds. See "HTTP INTERFACE".

debug_startup

    use Plack::Middleware::DBGp (
        debug_startup   => [0|1],
    );

Whether the debugger should try to connect to the debugger client as soon as it is loaded, during application startup.

log_path

    use Plack::Middleware::DBGp (
        log_path    => '/path/to/debugger.log',
    );

When set, will write debugging information from the debugger to the sepcified path.

enbugger

    use Plack::Middleware::DBGp (
        enbugger    => [0|1],
    );

Use Enbugger. At the moment it only enables debugging all files, even the ones loaded before Plack::Middleware::DBGp.

debug_client_path

    use Plack::Middleware::DBGp (
        debug_client_path   => '/path/to/dbgp-enabled/debugger',
    );

Use a Devel::Debug::DBGp installed outside the default module search path.

HTTP INTERFACE

When autostart is disabled, Plack::Middleware::DBGp emulates the Xdebug browser session interface.

The XDEBUG_SESSION_START=idekey GET/POST parameter starts a debugging session and sets the XDEBUG_SESSION cookie.

When the XDEBUG_SESSION cookie is set, the debugger tries to connect to the debugger client passing the sepcified IDE key.

The XDEBUG_SESSION_STOP GET/POST parameter clears the XDEBUG_SESSION cookie.

AUTHOR

Mattia Barbon <mbarbon@cpan.org>

LICENSE

Copyright (c) 2015-2016 Mattia Barbon. All rights reserved.

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