The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
prancer-0.01
++
/ Prancer

NAME

Prancer - Another PSGI Framework

SYNOPSIS

Prancer is yet another PSGI framework. This one is designed to be a bit smaller and more out of the way than others but it could probably be described best as project derived from NIH syndrome.

Here's how it might be used:

    ==> myapp.psgi

    use Prancer;
    my $app = Prancer->new("/path/to/confdir", "MyApp");
    $app->run();

    ==> MyApp.pm

    package MyApp;

    use Prancer::Application qw(:all);
    use parent qw(Prancer::Application);

    sub handle {
        my $self = shift;

        mount('GET', '/', sub {
            context->header(set => 'Content-Type', value => 'text/plain');
            context->body("hello world");
            context->finalize(200);
        });

        return dispatch;
    }

Full documentation can be found in Prancer::Manual.

INSTALLATION

To install this module, run the following commands:

    perl Makefile.PL
    make
    make test
    make install

If this ever makes it to CPAN you can install it with this simple command:

    perl -MCPAN -e 'install Prancer'

These optional libraries will enhance the functionality of Prancer:

Template

Without this the Prancer template interface will not work.

DBI

Without this the Prancer database interface will not work. You also will need a database driver like DBD::Pg.

Plack::Middleware::Session

Without this the Prancer session support will not work. If you want to use the YAML session storage you will also need to have YAML (preferably YAML::XS) installed. If you want support to write sessions do the database you will also need DBI installed along with a database driver like DBD::Pg.

EXPORTABLE

The following methods are exportable: config, logger, database, template. They can all be exported at once using :all.

METHODS

With the exception of ->new and ->run, all methods should be called in a static context. Additionally, with the same exception, all methods are exportable individually or with qw(:all).

->new CONFIG PACKAGE ARGS

This will create your application. It takes two arguments:

CONFIG

This a path to a directory containing configuration files. How configuration files are loaded is detailed below.

PACKAGE

This is the name of a package that implements your application. The package named should extend Prancer::Application though this is not enforced.

ARGS

After the name of the package, any number of arguments may be added. Any extra arguments are passed directly to the new method on the named package when it is created for a request.

->run

This starts your application. It takes no arguments.

logger

This gives access to the logger. For example:

    logger->info("Hello");
    logger->fatal("uh oh");
    logger->debug("here we are");
config

This gives access to the configuration. For example:

    config->has('foo');
    config->get('foo');
    config->set('foo', value => 'bar');
    config->remove('foo');

Any changes to the configuration do not persist back to the actual configuration file. Additionally they do not persist between threads or processes.

Whenever this method is used to get a configuration option and that option is reference, the reference will be cloned by Storable to prevent changes to one copy from affecting other uses. But this could have performance implications if you are routinely getting large data structures out if your configuration files.

template

This gives access to the configured template engine. For example:

    print template("foo.tt", {
        'title' => 'foobar',
        'var1' => 'val2',
    });

If no template engines are configured then this method will always return undef.

database

This gives access to the configured databases. For example:

    # handle to the database configured as 'default'
    my $dbh = database;

    # handle to the database configured as 'foo'
    my $dbh = database('foo');

    # prepare a statement on connection 'default'
    my $sth = database->prepare("SELECT * FROM foo");

In all cases, $dbh will be a reference to a DBI handle and anything that can be done with DBI can be done here.

If no databases are configured then this method will always return undef.

session

Configures the session handler. For example:

    session:
        state:
            driver: Prancer::Session::State::Cookie
            options:
                key: PSESSION
        store:
            driver: Prancer::Session::Store::YAML
            options:
                path: /tmp/prancer/sessions

See Prancer::Session::State::Cookie, Prancer::Session::Store::Memory, Prancer::Session::Store::YAML and Prancer::Session::Store::Database for more options.

CONFIGURATION

One doesn't need to create any configuration to use Prancer but then Prancer wouldn't be very useful. Prancer uses Config::Any to process configuration files so anything supported by that will be supported by this. It will load configuration files from given path set when your application initialized. First it will look for a file named config.ext where ext is something like yml or ini. Then it will look for a file named after the current environment like develoment.ext or production.ext. The environment is derived by looking first for an environment variable called ENVIRONMENT, then for an environment variable called PLACK_ENV. If neither of those exist then the default is development. Configuration files will be merged such that the environment configuration file will take precedence over the global configuration file.

Arbitrary configuration directives can be put into your configuration files and they can be accessed like this:

    config(get => 'foo');

The configuration accessors will only give you configuration directives found at the root of the configuration file. So if you use any data structures you will have to decode them yourself. For example, if you create a YAML file like this:

    foo:
        bar1: asdf
        bar2: fdsa

Then you will only be able to get the value to bar1 like this:

    my $foo = config(get => 'foo')->{'bar1'};

Reserved Configuration Options

To support the components of Prancer, these keys are used:

logger

Configures the logging system. For example:

    logger:
        driver: Prancer::Logger::WhateverLogger
        options:
            level: debug

For the console logger, see Prancer::Logger::Console for more options.

template

Configures the templating system. For example:

    template:
        driver: Prancer::Template::WhateverEngine
        options:
            template_dir: /srv/www/site/templates
            encoding: utf8
            start_tag: "<%"
            end_tag: "%>"

For the Template Toolkit plugin, see Prancer::Template::TemplateToolkit for more options.

database

Configures database connections. For example:

    database:
        default:
            driver: Prancer::Database::Driver::WhateverDriver
            options:
                username: test
                password: test
                database: test

See Prancer::Database for more options.

static

Configures a directory where static documents can be found and served using Plack::Middleware::Static. For example:

    static:
        path: /srv/www/site/static

The only configuration option for static documents is path. If this path is not defined your application will not start. If this path does not point to a directory that is readable your application will not start.

CREDITS

Large portions of this library were taken from the following locations and projects:

COPYRIGHT

Copyright 2013, 2014 Paul Lockaby. All rights reserved.

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