/ 
Log-Report-1.06
River stage two • 36 direct dependents • 86 total dependents
/ Dancer2::Plugin::LogReport

NAME

Dancer2::Plugin::LogReport - logging and exceptions via Log::Report

SYNOPSIS

# Load the plugin into Dancer2
# see Log::Report::import() for %options
use Dancer2::Plugin::LogReport %options;

# Stop execution, redirect, and display an error to the user
$name or error "Please enter a name";

# Add debug information to logger
trace "We're here";

# Handling user errors cleanly
if (process( sub {MyApp::Model->create_user} )) {
    # Success, redirect user elsewhere
} else {
    # Failed, continue as if submit hadn't been made.
    # Error message will be in session for display later.
}

# Send errors to template for display
hook before_template => sub {
    my $tokens = shift;
    $tokens->{messages} = session 'messages';
    session 'messages' => [];
}

DESCRIPTION

This module provides easy access to the extensive logging facilities provided by Log::Report. Along with Dancer2::Logger::LogReport, this brings together all the internal Dancer2 logging, handling for expected and unexpected exceptions, translations and application logging.

Logging is extremely flexible using many of the available dispatchers. Multiple dispatchers can be used, each configured separately to display different messages in different formats. By default, messages are logged to a session variable for display on a webpage, and to STDERR.

METHODS

$obj->process()

process() is an eval, but one which expects and handles exceptions generated by Log::Report. Any messages will be logged as normal in accordance with the dispatchers, but any fatal exceptions will be caught and handled gracefully. This allows much simpler error handling, rather than needing to test for lots of different scenarios.

In a module, it is enough to simply use the error keyword in the event of a fatal error.

The return value will be 1 for success or 0 if a fatal exception occurred.

See the "DETAILS" for an example of how this is expected to be used.

Modules do not need to use this plugin, instead they can use Log::Report.

Handlers

All the standard Log::Report functions are available to use. Please see the "The Reason for the report" in Log::Report for details of when each one should be used.

$obj->alert()
$obj->assert()
$obj->error()
$obj->failure()
$obj->fault()
$obj->info()
$obj->mistake()
$obj->notice()
$obj->panic()
$obj->trace()
$obj->warning()

DETAILS

Larger example

In its simplest form, this module can be used for more flexible logging

 get '/route' => sub {
     # Stop execution, redirect, and display an error to the user
     $name or error "Please enter a name";

     # The same but translated
     $name or error __"Please enter a name";
 
     # The same but translated and with variables
     $name or error __x"{name} is not valid", name => $name;

     # Show the user a warning, but continue exection
     mistake "Not sure that's what you wanted";

     # Add debug information, can be caught in syslog by adding the syslog
     # dispatcher
     trace "Hello world"; };

The module can also be used in models to test for user input and act accordingly, without needing to set up complicated error handling:

# In a module
package MyApp::MyModel sub create_user {
    ...
    $surname or error "Please enter a surname"; # Execution stops here
    ...
    $telephone or mistake "Tel not entered"; # Execution continues
    ...
}

# In the main app
get '/user' => sub {
    ...
    if (param 'submit') {
        if (process( sub { MyApp::Model->create_user() })) {
            # Success, redirect user elsewhere
        }
    }
    # Failed, continue as if submit hadn't been made. Error will have been
    # logged in session to be displayed later.
};

This module will also catch any unexpected exceptions:

# This will be caught, the error will be logged (full stacktrace to STDOUT,
# short message to the session messages), and the user will be forwarded
# (default to /). This would also be sent to syslog with the appropriate
# dispatcher.
get 'route' => sub {
    my $foo = 1;
    my $bar = $foo->{x}; # whoops
}

Errors are all logged to the session. These need to be cleared once they have been displayed.

hook before_template => sub {
    my $tokens = shift;
    # Pass messages to template and clear session
    $tokens->{messages} = session 'messages';
    session 'messages' => [];
}

In the template. This example prints them in Bootstrap colors:

[% FOR message IN messages %]
    [% IF message.type %]
        [% msgtype = message.type %]
    [% ELSE %]
        [% msgtype = "info" %]
    [% END %]
    <div class="alert alert-[% msgtype %]">
        [% message.text | html_entity %]
    </div>
[% END %]

Configuration

Dancer2 configuration

In your application's configuration file (values shown are defaults):

plugins: LogReport
        # Set the forward URL on fatal error that isn't caught
        forward_url: /

        # Set to 1 if you want the module to also catch Dancer HTTP errors
        # (such as 404s)
        handle_http_errors: 0

        # Configure session variable for messages
        messages_key = messages

Log::Report configuration

Any Log::Report configuration options can also be used with this plugin.

Dancer2::Logger::LogReport

You probably want to also use and configure Dancer2::Logger::LogReport. See its documentation for full details.

SEE ALSO

This module is part of Log-Report distribution version 1.06, built on June 15, 2015. Website: http://perl.overmeer.net/log-report/

LICENSE

Copyrights 2007-2015 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html