NAME

MojoX::Log::Dispatch::Simple - Simple Log::Dispatch replacement of Mojo::Log

VERSION

version 1.11

SYNOPSIS

    # from inside your startup() most likely...

    use Log::Dispatch;
    use MojoX::Log::Dispatch::Simple;

    my $mojo_logger = MojoX::Log::Dispatch::Simple->new(
        dispatch => Log::Dispatch->new,
        level    => 'debug'
    );

    my ($self) = @_; # Mojolicious object from inside startup()
    $self->log($mojo_logger);

    # ...then later inside a controller...

    $self->app->log->debug('Debug-level message');
    $self->app->log->info('Info-level message');

    # ...or back to your startup() to setup some helpers...

    $mojo_logger->helpers($self);
    $mojo_logger->helpers( $self, qw( debug info warn error ) );

    # ...so that in your controllers you can...

    $self->debug('Debug-level message');
    $self->info('Info-level message');

    # ...or do it all at once, in the startup() most likely...

    $self->log( MojoX::Log::Dispatch::Simple->new(
        dispatch => Log::Dispatch->new,
        level    => 'debug'
    )->helpers($self) );

DESCRIPTION

This module provides a really simple way to replace the built-in Mojo::Log with a Log::Dispatch object, and yet still support all the Mojo::Log log levels and other functionality Mojolicious assumes exists. To make it even easier, you can install helpers to all the log levels, all from the same single line of code.

    $self->log( MojoX::Log::Dispatch::Simple->new(
        dispatch => Log::Dispatch->new,
        level    => 'debug'
    )->helpers($self) );

The module tries not to make any assumptions about how you want to use Log::Dispatch. In fact, you can if desired use an alternate Log::Dispatch library so long as it offers a similar interface.

PRIMARY METHODS

These are methods that you would likely use from within your Mojolicious "startup()" subroutine.

new

This method instantiates an object. It requires a "dispatch" parameter, which should be a Log::Dispatch object (or an object with a similar signature). The method allow accepts an optional "level" parameter, which is used to set the log level for your Mojolicious application.

    my $mojo_logger = MojoX::Log::Dispatch::Simple->new(
        dispatch => Log::Dispatch->new,
        level    => 'debug'
    );

Optionally, you can also provide a "format_cb" value, which should be a reference to a subroutine that will be used to provide custom formatting to entries that appear on the Mojolicious error reporting web page. This formatting will have nothing at all to do with whatever your Log::Dispatch does; it only formats log entries that appear on the Mojolicious error reporting web page.

    my $mojo_logger = MojoX::Log::Dispatch::Simple->new(
        dispatch  => Log::Dispatch->new,
        level     => 'debug',
        format_cb => sub {
            localtime(shift) . ' [' . shift() . '] ' . join( "\n", @_, '' )
        },
    );

By default, when you're looking at one of these Mojolicious error reporting web pages, you'll see the past 10 log entries listed. You can change that by passing in a "max_history_size" value.

    my $mojo_logger = MojoX::Log::Dispatch::Simple->new(
        dispatch         => Log::Dispatch->new,
        max_history_size => 20,
    );

helpers

You can optionally tell this library to create helpers to each of the log levels, or to a selection of them. This method requires that you pass in a reference to the Mojolicious object. If that's all you pass in, the method will create a helper for every log level.

    # from inside your startup()...
    $mojo_logger->helpers($mojo_obj);

    # now later from inside a controller...
    $c->debug('Debug message');

    $c->app->log->debug("This is what you'd have to type without the helper");

You can optionally pass in the names of the log levels you want helpers created for, and the method will only create methods for those levels.

    $mojo_logger->helpers( $mojo_obj, qw( debug info warn ) );

LOG LEVELS

Unfortunately, Mojolicious and Log::Dispatch have somewhat different ideas as to what log levels should exist. Since this module is a bridge between them, it attempts to support all levels from both sides. That being said, when calling log levels in your application, you will probably want to only use the log levels from Log::Dispatch if you use your Log::Dispatch code in non-Mojo-app areas of your ecosystem, thus keeping things uniform everywhere.

For the purposes of understanding log levels relative to each other, all log levels are assigned a "rank" value. Since Mojolicious has fewer levels than Log::Dispatch and there are 5 of them, a level's "rank" is an integer between 1 and 5.

Log::Dispatch Log Levels

The following are Log::Dispatch log levels along with their corresponding "rank" integer and any supported aliases:

debug (1)
info (2)
notice (2)
warning, warn (3)
error, err (4)
critical, crit (4)
alert (5)
emergency, emerg (5)

Mojolicious Log Levels

The following are Mojolicious log levels along with their corresponding "rank" integer and any supported aliases:

debug (1)
info (2)
warn (3)
error (4)
fatal (5)

You can check what log level you're set at by either just reading "$obj-"level> or by running an "is_*" method. For every log level, there's a corresponding "is_*" method.

    my $log_level_at_or_above_notice = $obj->is_notice;

Note that this gets somewhat confusing when dealing with Log::Dispatch log levels because from the perspective of Log::Dispatch, the "notice" level is a unique level that's lower than a "warning" and higher than the "info" level. However, from the perspective of Mojolicious, there's no such log level. It will assume you're set at the "info" log level. Ergo, if you call "is_notice()" or "is_info()", you'll get the same result.

POST-INSTANTIATION MEDDLING

Following the creation of the object from this library, you can still manipulate various attributes, which are:

dispatch (a Log::Dispatch object)
level
max_history_size
format_cb (a subref)
history (an arrayref)

So you can do things like:

    $obj->dispatch->remove('debug');

This also means you can manipulate the log history. Why you'd ever want to do that, I can't say; but you can. Freedom is messy.

GRATITUDE

Special thanks to the following for contributing to this module:

•: Tomohiro Hosaka

AUTHOR

Gryphon Shafer <gryphon@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)