NAME

Log::Handler::Plugin::DBI - A plugin for Log::Handler using Log::Hander::Output::DBI

Synopsis

Firstly, use your config file to connect to the db and create the 'log' table.

Then:

        package My::App;

        use strict;
        use warnings;

        use Config::Plugin::Tiny; # For config_tiny().

        use File::Spec;

        use Log::Handler::Plugin::DBI; # For configure_logger() and log().

        # ------------------------------------------------

        sub marine
        {
                my($self)   = @_;
                my($config) = $self -> config_tiny(File::Spec -> catfile('some', 'dir', 'config.tiny.ini') );

                $self -> configure_logger($$config{logger});

                $self -> log(debug => 'Hi from sub marine()');

        } # End of marine.

        # --------------------------------------------------

        1;

t/config.logger.ini is used in the test file t/test.t, and also ships with the CGI::Snapp::Demo::Four distro.

Description

When you 'use' this module (as in the Synopsis), it automatically imports into your class several methods. See "Methods" for details.

Distributions

This module is available as a Unix-style distro (*.tgz).

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.

Installation

Install Log::Handler::Plugin::DBI as you would for any Perl module:

Run:

        cpanm Log::Handler::Plugin::DBI

or run:

        sudo cpan Log::Handler::Plugin::DBI

or unpack the distro, and then either:

        perl Build.PL
        ./Build
        ./Build test
        sudo ./Build install

or:

        perl Makefile.PL
        make (or dmake or nmake)
        make test
        make install

Constructor and Initialization

This module does not have, and does not need, a constructor.

Methods

configure_logger($hashref)

Configures the internal log object with these parameters from $hashref:

o dsn => $string: A typical $string might be 'dbi:SQLite:dbname=/tmp/logger.test.sqlite'.
o username => $string: Supply your database server username, or leave empty for databases such as SQLite.
o password => $string: Supply your database server password, or leave empty for databases such as SQLite.
o table_name => $string: Supply your log table name, or let it default to 'log'.

log($level => $message)

Logs $message at $level.

See Log::Handler#LOG-LEVELS and Log::Handler::Levels.

log_object()

Returns the internal log object, for those cases when you want to pass it to some other class.

See the CGI::Snapp::Demo::Four distro, which contains httpd/cgi-bin/cgi.snapp.demo.four.cgi, which uses CGI::Snapp::Demo::Four::Wrapper.

The latter passes this log object to CGI::Snapp's logger() method, to demonstrate logging a CGI script's method call sequence to a database table.

FAQ

When would I use this module?

In your sub-class of CGI::Snapp for example, or anywhere else you want to log to a database.

See Log::Handler::Plugin::DBI::CreateTable for help creating a 'log' table.

For sample code, study CGI::Snapp::Demo::Four.

What is the expected structure of the 'log' table?

See the "FAQ" in Log::Handler::Plugin::DBI::CreateTable. In pseudo-code:

        id primary key + (db_vendor-dependent stuff)
        level varchar(255) not null,
        message not null + (db_vendor eq 'ORACLE' ? 'long' : 'text')
        timestamp timestamp not null default current_timestamp +
        (db_vendor =~ /(?:MySQL|Postgres)/i ? '(0) without time zone' : '')

Also, if you're using MySQL, you might want to set the engine=innodb option.

See scripts/create.table.pl and scripts/drop.table.pl for an easy way to do all this.

Can this module be used in any module?

Yes. See t/test.t, which passes undef as the first parameter to each method, because there is no $self available.

Alternately, if you 'use' this module within any other module, calling $self -> log() will work.

It's used in CGI::Snapp::Demo::Four::Wrapper, which inherits from CGI::Snapp::Demo::Four, which inherits from CGI::Snapp. So, even though CGI::Snapp has its own log() method, the one imported from the current module overrides that one.

Why can't I call $log_object -> info($message) etc as with Log::Handler?

Because it's not true that an object of type Log::Handler::Output::DBI (the underlying object here) 'isa' Log::Handler.

Why don't you 'use Exporter;'?

It is not needed; it would be for documentation only.

For the record, Exporter V 5.567 ships with Perl 5.8.0. That's what I had in Build.PL and Makefile.PL until I tested the fact I can omit it.

Machine-Readable Change Log

The file CHANGES was converted into Changelog.ini by Module::Metadata::Changes.

Version Numbers

Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Credits

Please read https://metacpan.org/module/CGI::Application::Plugin::Config::Simple#AUTHOR, since a lot of the ideas for this module were copied from CGI::Application::Plugin::Config::Simple.

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=Log::Handler::Plugin::DBI.

Author

Log::Handler::Plugin::DBI was written by Ron Savage <ron@savage.net.au> in 2012.

Home page: http://savage.net.au/index.html.

Copyright

        All Programs of mine are 'OSI Certified Open Source Software';
        you can redistribute them and/or modify them under the terms of
        The Artistic License, a copy of which is available at:
        http://www.opensource.org/licenses/index.html