=encoding utf8

=head1 NAME

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

=head1 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' => [];
  }

=head1 DESCRIPTION

This module provides easy access to the extensive logging facilities
provided by L<Log::Report|Log::Report>. Along with L<Dancer2::Logger::LogReport|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
L<dispatchers|Log::Report::Dispatcher/DETAILS>.  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.

=head1 METHODS

=over 4

=item $obj-E<gt>B<process>()

C<process()> is an eval, but one which expects and handles exceptions
generated by L<Log::Report|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 C<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 L</DETAILS> for an example of how this is expected to be used.

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

=back

=head2 Handlers

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

=over 4

=item $obj-E<gt>B<alert>()

=item $obj-E<gt>B<assert>()

=item $obj-E<gt>B<error>()

=item $obj-E<gt>B<failure>()

=item $obj-E<gt>B<fault>()

=item $obj-E<gt>B<info>()

=item $obj-E<gt>B<mistake>()

=item $obj-E<gt>B<notice>()

=item $obj-E<gt>B<panic>()

=item $obj-E<gt>B<trace>()

=item $obj-E<gt>B<warning>()

=back

=head1 DETAILS

=head2 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 %]

=head2 Configuration

=head3 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

=head3 Log::Report configuration

Any L<Log::Report configuration options|Log::Report/Configuration> can also be
used with this plugin.

=head3 Dancer2::Logger::LogReport

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

=head1 SEE ALSO

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

=head1 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 F<http://www.perl.com/perl/misc/Artistic.html>

