Stefan G. > Kelp > Kelp

Download:
Kelp-0.9012.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.9012   Source  

NAME ^

Kelp - A web framework light, yet rich in nutrients.

SYNOPSIS ^

First ...

    # lib/MyApp.pm
    package MyApp;
    use parent 'Kelp';

    sub build {
        my $self = shift;
        my $r = $self->routes;
        $r->add( "/hello", sub { "Hello, world!" } );
        $r->add( '/hello/:name', 'greet' );
    }

    sub greet {
        my ( $self, $name ) = @_;
        "Hello, $name!";
    }

    1;

Then ...

    # app.psgi
    use MyApp;
    my $app = MyApp->new;
    $app->run;

Finally ...

    > plackup app.psgi

Or, for quick prototyping use Kelp::Less:

    # app.psgi
    use Kelp::Less;

    get '/hello/?name' => sub {
        my ( $self, $name ) = @_;
        "Hello " . $name // 'world';
    };

    run;

DESCRIPTION ^

If you're going to be deploying a Perl based web application, chances are that you will be using Plack. Plack has almost all necessary tools to create and maintain a healthy web app. Tons of middleware is written for it, and there are several very well tested high performance preforking servers, such as Starman.

Plack, however, is not a web framework, hence its creators have intentionally omitted adding certain components. This is where Kelp gets to shine. It provides a layer on top of Plack and puts everything together into a complete web framework.

Kelp provides:

WHY KELP? ^

What makes Kelp different from the other Perl micro web frameworks? There are a number of fine web frameworks on CPAN, and most of them provide a complete platform for web app building. Most of them, however, bring their deployment code, and aim to write their own processing mechanisms. Kelp, on the other hand, is heavily Plack-centric. It uses Plack as its foundation layer, and it builds the web framework on top of it. Kelp::Request is an extension of Plack::Request, Kelp::Response is an extension of Plack::Response.

This approach of extending current CPAN code puts familiar and well tested tools in the hands of the application developer, while keeping familiar syntax and work flow.

Kelp is a team player and it uses several popular, trusted CPAN modules for its internals. At the same time it doesn't include modules that it doesn't need, just because they are considered trendy. It does its best to keep a lean profile and a small footprint, and it's completely object manager agnostic.

CREATING A NEW WEB APP ^

Using the Kelp script

The easiest way to create the directory structure and a general application skeleton is by using the Kelp script, which comes with this package.

    > Kelp MyApp

This will create lib/MyApp.pm, app.psgi and some other files (explained below).

To create a Kelp::Less app, use:

    > Kelp --less MyApp

Get help by typing:

    > Kelp --help

Directory structure

Before you begin writing the internals of your app, you need to create the directory structure either by hand, or by using the above described Kelp utility script.

     .
     |--/lib
     |   |--MyApp.pm
     |   |--/MyApp
     |
     |--/conf
     |   |--config.pl
     |   |--test.pl
     |   |--development.pl
     |   |--deployment.pl
     |
     |--/view
     |--/log
     |--/t
     |--app.psgi
/lib

The lib folder contains your application modules and any local modules that you want your app to use.

/conf

The conf folder is where Kelp will look for configuration files. You need one main file, named config.pl. You can also add other files that define different running environments, if you name them environment.pl. Replace environment with the actual name of the environment. To change the running environment, you can specify the app mode, or you can set the PLACK_ENV environment variable.

    my $app = MyApp->new( mode => 'development' );

or

    > PLACK_ENV=development plackup app.psgi
/view

This is where the Template module will look for template files.

/log

This is where the Logger module will create error.log, debug.log and any other log files that were defined in the configuration.

/t

The t folder is traditionally used to hold test files. It is up to you to use it or not, although we strongly recommend that you write some automated test units for your web app.

app.psgi

This is the PSGI file, of the app, which you will deploy. In it's most basic form it should look like this:

    use lib '../lib';
    use MyApp;

    my $app = MyApp->new;
    $app->run;

The application classes

Your application's classes should be put in the lib/ folder. The main class, in our example MyApp.pm, initializes any modules and variables that your app will use. Here is an example that uses Moose to create lazy attributes and initialize a database connection:

    package MyApp;

    use parent Kelp;
    use Moose;

    has dbh => (
        is      => 'ro',
        isa     => 'DBI',
        lazy    => 1,
        default => sub {
            my $self   = shift;
            my @config = @{ $self->config('dbi') };
            return DBI->connect(@config);
        }
    );

    sub build {
        my $self = shift;
        $self->routes->add("/read/:id", "read");
    }

    sub read {
        my ( $self, $id ) = @_;
        $self->dbh->selectrow_array(q[
            SELECT * FROM problems
            WHERE id = ?
        ], $id);
    }

    1;

What is happening here?

A note about object managers: The above example uses Moose. It is entirely up to you to use Moose, another object manager, or no object manager at all. The above example will be just as successful if you used our own little Kelp::Base:

    package MyApp;
    use Kelp::Base 'Kelp';

    attr dbi => sub {
        ...
    };

    1;

Routing

Kelp uses a powerful and very flexible router. Traditionally, it is also light and consists of less than 300 lines of code (comments included). You are encouraged to read Kelp::Routes, but here are some key points. All examples are assumed to be inside the "build" method and $r is equal to $self->routes:

Destinations

You can direct HTTP paths to subroutines in your classes or, you can use inline code.

    $r->add( "/home", "home" );  # goes to sub home
    $r->add( "/legal", "Legal::view" ); # goes to MyApp::Legal::view
    $r->add( "/about", sub { "Content for about" }); # inline

Restrict HTTP methods

Make a route only catch a specific HTTP method:

    $r->add( [ POST => '/update' ], "update_user" );

Named captures

Using regular expressions is so Perl. Sometimes, however, it gets a little overwhelming. Use named paths if you anticipate that you or someone else will ever want to maintain your code.

Explicit

    $r->add( "/update/:id", "update" );

    # Later
    sub update {
        my ( $self, $id ) = @_;
        # Do something with $id
    }

Optional

    $r->add( "/person/?name", sub {
        my ( $self, $name ) = @_;
        return "I am " . $name // "nobody";
    });

This will handle /person, /person/ and /person/jack.

Wildcards

    $r->add( '/*article/:id', 'Articles::view' );

This will handle /bar/foo/baz/500 and send it to MyApp::Articles::view with parameters $article equal to bar/foo/baz and $id equal to 500.

Placeholder restrictions

Paths' named placeholders can be restricted by providing regular expressions.

    $r->add( '/user/:id', {
        check => { id => '\d+' },
        to    => "Users::get"
    });

    # Matches /user/1000, but not /user/abc

Placeholder defaults

This only applies to optional placeholders, or those prefixed with a question mark. If a default value is provided for any of them, it will be used in case the placeholder value is missing.

    $r->add( '/:id/?other', defaults => { other => 'info' } );

    # GET /100;
    # { id => 100, other => 'info' }

    # GET /100/delete;
    # { id => 100, other => 'delete' }

Bridges

A bridge is a route that has to return a true value in order for the next route in line to be processed.

    $r->add( '/users', { to => 'Users::auth', bridge => 1 } );
    $r->add( '/users/:action' => 'Users::dispatch' );

See "BRIDGES" in Kelp::Routes for more information.

URL building

Each path can be given a name and later a URL can be built using that name and the necessary arguments.

    $r->add( "/update/:id", { name => 'update', to => 'User::update' } );

    # Later

    my $url = $self->route->url('update', id => 1000); # /update/1000

Reblessing the app into a controller class

All of the examples here show routes which take an instance of the web application as a first parameter. This is true even if those routes live in another class. To rebless the app instance into the controller class instance, use the custom router class Kelp::Router::Controller.

Step 1: Specify the custom router class in the config

    # config.pl
    {
        modules_init => {
            Routes => {
                router => 'Controller'
            }
        }
    }

Step 2: Create a main controller class

This class must inherit from Kelp.

    # lib/MyApp/Controller.pm
    package MyApp::Controller;
    use Kelp::Base 'MyApp';

    # Now $self is an instance of 'MyApp::Controller';
    sub service_method {
        my $self = shift;
        ...;
    }

    1;

Step 3: Create any number of controller classes

They all must inherit from your main controller class.

    # lib/MyApp/Controller/Users.pm
    package MyApp::Controller::Users;
    use Kelp::Base 'MyApp::Controller';

    # Now $self is an instance of 'MyApp::Controller::Users'
    sub authenticate {
        my $self = shift;
        ...;
    }

    1;

Quick development using Kelp::Less

For writing quick experimental web apps and to reduce the boiler plate, one could use Kelp::Less. In this case all of the code can be put in app.psgi: Look up the POD for Kelp::Less for many examples, but to get you started off, here is a quick one:

    # app.psgi
    use Kelp::Less;

    get '/api/:user/?action' => sub {
        my ( $self, $user, $action ) = @_;
        my $json = {
            success => \1,
            user    => $user,
            action  => $action // 'ask'
        };
        return $json;
    };

    run;

Adding middleware

Kelp, being Plack-centric, will let you easily add middleware. There are three possible ways to add middleware to your application, and all three ways can be used separately or together.

Using the configuration

Adding middleware in your configuration is probably the easiest and best way for you. This way you can load different middleware for each running mode, e.g. Debug in development only.

Add middleware names to the middleware array in your configuration file and the corresponding initializing arguments in the middleware_init hash:

    # conf/development.pl
    {
        middleware      => [qw/Session Debug/],
        middleware_init => {
            Session => { store => 'File' }
        }
    }

The middleware will be added in the order you specify in the middleware array.

In app.psgi:

    # app.psgi
    use MyApp;
    use Plack::Builder;

    my $app = MyApp->new();

    builder {
        enable "Plack::Middleware::ContentLength";
        $app->run;
    };

By overriding the "run" subroutine in lib/MyApp.pm:

Make sure you call SUPER first, and then wrap new middleware around the returned app.

    # lib/MyApp.pm
    sub run {
        my $self = shift;
        my $app = $self->SUPER::run(@_);
        Plack::Middleware::ContentLength->wrap($app);
    }

Note that any middleware defined in your config file will be added first.

Deploying

Deploying a Kelp application is done the same way any other Plack application is deployed:

    > plackup -E deployment -s Starman app.psgi

Testing

Kelp provides a test class called Kelp::Test. It is object oriented, and all methods return the Kelp::Test object, so they can be chained together. Testing is done by sending HTTP requests to an already built application and analyzing the response. Therefore, each test usually begins with the "request" in Kelp::Test method, which takes a single HTTP::Request parameter. It sends the request to the web app and saves the response as an HTTP::Response object.

    # file t/test.t
    use MyApp;
    use Kelp::Test;
    use Test::More;
    use HTTP::Request::Common;

    my $app = MyApp->new( mode => 'test' );
    my $t = Kelp::Test->new( app => $app );

    $t->request( GET '/path' )
      ->code_is(200)
      ->content_is("It works");

    $t->request( POST '/api' )
      ->json_cmp({auth => 1});

    done_testing;

What is happening here?

Run the rest as usual, using prove:

    > prove -l t/test.t

Take a look at the Kelp::Test for details and more examples.

Building an HTTP response

Kelp contains an elegant module, called Kelp::Response, which extends Plack::Response with several useful methods. Most methods return $self after they do the required job. For the sake of the examples below, let's assume that all of the code is located inside a route definition.

Automatic content type

Your routes don't always have to set the response object. You could just return a simple scalar value or a reference to a hash, array or anything that can be converted to JSON.

    # Content-type automatically set to "text/html"
    sub text_route {
        return "There, there ...";
    }

    # Content-type automatically set to "application/json"
    sub json_route {
        return { error => 1,  message => "Fail" };
    }

Rendering text

    # Render simple text
    $self->res->text->render("It works!");

Rendering HTML

    $self->res->html->render("<h1>It works!</h1>");

Custom content type

    $self->res->set_content_type('image/png');

Return 404 or 500 errors

    sub some_route {
        my $self = shift;
        if ($missing) {
            return $self->res->render_404;
        }
        if ($broken) {
            return $self->res->render_500;
        }
    }

Templates

    sub hello {
        my ( $self, $name ) = @_;
        $self->res->template( 'hello.tt', { name => $name } );
    }

The above example will render the contents of hello.tt, and it will set the content-type to text/html. To set a different content-type, use set_content_type or any of its aliases:

    sub hello_txt {
        my ( $self, $name ) = @_;
        $self->res->text->template( 'hello_txt.tt', { name => $name } );
    }

Headers

    $self->set_header( "X-Framework", "Kelp" )->render( { success => \1 } );

Serving static files

If you want to serve static pages, you can use the Plack::Middleware::Static middleware that comes with Plack. Here is an example configuration that serves files in your public folder (under the Kelp root folder) from URLs that begin with /public:

    # conf/config.pl
    {
        middleware      => [qw/Static/],
        middleware_init => {
            Static => {
                path => qr{^/public/},
                root => '.',
            }
        }
    };

Uploading files

File uploads are handled by Kelp::Request, which inherits Plack::Request and has its uploads|Plack::Request/uploads property. The uploads property returns a reference to a hash containing all uploads.

    sub upload {
        my $self = shift;
        my $uploads  = $self->req->uploads;

        # Now $uploads is a hashref to all uploads
        ...
    }

For Kelp::Less, then you can use the req reserved word:

    get '/upload' => sub {
        my $uploads = req->uploads;
    };

Delayed responses

To send a delayed response, have your route return a subroutine.

    sub delayed {
        my $self = shift;
        return sub {
            my $responder = shift;
            $self->res->code(200);
            $self->res->text->body("Better late than never.");
            $responder->($self->res->finalize);
        };
    }

See the PSGI pod for more information and examples.

Pluggable modules

Kelp can be extended using custom modules. Each new module must be a subclass of the Kelp::Module namespace. Modules' job is to initialize and register new methods into the web application class. The following is the full code of the Kelp::Module::JSON for example:

    package Kelp::Module::JSON;

    use Kelp::Base 'Kelp::Module';
    use JSON;

    sub build {
        my ( $self, %args ) = @_;
        my $json = JSON->new;
        $json->property( $_ => $args{$_} ) for keys %args;
        $self->register( json => $json );
    }

    1;

What is happening here?

If we instruct our web application to load the JSON module, it will have a new method json which will be a link to the JSON object initialized in the module.

See more exampled and POD at Kelp::Module.

How to load modules using the config

There are two modules that are always loaded by each application instance. Those are Config and Routes. The reason behind this is that each and every application always needs a router and configuration. All other modules must be loaded either using the "load_module" method, or using the modules key in the configuration. The default configuration already loads these modules: Template, Logger and JSON. Your configuration can remove some and/or add others. The configuration key modules_init may contain hashes with initialization arguments. See Kelp::Module for configuration examples.

ATTRIBUTES ^

hostname

Gets the current hostname.

    sub some_route {
        my $self = shift;
        if ( $self->hostname eq 'prod-host' ) {
            ...
        }
    }

mode

Sets or gets the current mode. The mode is important for the app to know what configuration file to merge into the main configuration. See Kelp::Module::Config for more information.

    my $app = MyApp->new( mode => 'development' );
    # conf/config.pl and conf/development.pl are merged with priority
    # given to the second one.

config_module

Sets of gets the class of the configuration module to be loaded on startup. The default value is Config, which will cause the Kelp::Module::Config to get loaded. See the documentation for Kelp::Module::Config for more information and for an example of how to create and use other config modules.

loaded_modules

A hashref containing the names and instances of all loaded modules. For example, if you have these two modules loaded: Template and JSON, then a dump of the loaded_modules hash will look like this:

    {
        Template => Kelp::Module::Template=HASH(0x208f6e8),
        JSON     => Kelp::Module::JSON=HASH(0x209d454)
    }

This can come handy if your module does more than just registering a new method into the application. Then, you can use its object instance to do access that additional functionality.

path

Gets the current path of the application. That would be the path to app.psgi

name

Gets or sets the name of the application. If not set, the name of the main class will be used.

    my $app = MyApp->new( name => 'Twittar' );

charset

Sets of gets the encoding charset of the app. It will be UTF-8, if not set to anything else. The charset could also be changed in the config files.

long_error

When a route dies, Kelp will by default display a short error message. Set this attribute to a true value, if you need to see a full stack trace of the error. The KELP_LONG_ERROR environment variable can also set this attribute.

req

This attribute only makes sense if called within a route definition. It will contain a reference to the current Kelp::Request instance.

    sub some_route {
        my $self = shift;
        if ( $self->req->is_json ) {
            ...
        }
    }

res

This attribute only makes sense if called within a route definition. It will contain a reference to the current Kelp::Response instance.

    sub some_route {
        my $self = shift;
        $self->res->json->render( { success => 1 } );
    }

METHODS ^

build

On it's own the build method doesn't do anything. It is called by the constructor, so it can be overridden to add route destinations and initializations.

    package MyApp;

    sub build {
        my $self = shift;
        my $r = $self->routes;

        # Load some modules
        $self->load_module("MongoDB");
        $self->load_module("Validate");

        # Add all route destinations
        $r->add("/one", "one");
        ...

    }

load_module

load_module($name, %options)

Used to load a module. All modules must be under the Kelp::Module:: namespace.

    $self->load_module("Redis", server => '127.0.0.1');
    # Will look for and load Kelp::Module::Redis

Options for the module may be specified after its name, or in the modules_init hash in the config. The precedence is given to the inline options. See Kelp::Module for more information on making and using modules.

build_request

This method is used to create the request object for each HTTP request. It returns an instance of Kelp::Request, initialized with the current request's environment. You can override this method to use a custom request module.

    package MyApp;
    use MyApp::Request;

    sub build_request {
        my ( $self, $env ) = @_;
        return MyApp::Request->new( app => $app, env => $env );
    }

    # Now each request will be handled by MyApp::Request

before_finalize

Override this method, to modify the response object just before it gets finalized.

    package MyApp;

    sub before_finalize {
        my $self = shift;
        $self->res->set_header("X-App-Name", "MyApp");
    }

    ...

The above is an example of how to insert a custom header into the response of every route.

build_response

This method creates the response object, e.g. what an HTTP request will return. By default the object created is Kelp::Response. Much like "build_request", the response can also be overridden to use a custom response object.

run

This method builds and returns the PSGI app. You can override it in order to include middleware. See "Adding middleware" for an example.

param

A shortcut to $self->req->param:

    sub some_route {
        my $self = shift;
        if ( $self->param('age') > 18 ) {
            $self->can_watch_south_path(1);
        }
    }

See Kelp::Request for more information and examples.

session

A shortcut to $self->req->session. Take a look at "session" in Kelp::Request for more information and examples.

stash

Provides safe access to $self->req->stash. When called without arguments, it will return the stash hash. If called with a single argument, it will return the value of the corresponding key in the stash. See "stash" in Kelp::Request for more information and examples.

named

Provides safe access to $self->req->named. When called without arguments, it will return the named hash. If called with a single argument, it will return the value of the corresponding key in the named hash. See "named" in Kelp::Request for more information and examples.

url_for

A safe shortcut to $self->routes->url. Builds a URL from path and arguments.

    sub build {
        my $self = shift;
        $self->routes->add("/:name/:id", { name => 'name', to => sub {
            ...
        }});
    }

    sub check {
        my $self = shift;
        my $url_for_name = $self->url_for('name', name => 'jake', id => 1003);
        $self->res->redirect_to( $url_for_name );
    }

SUPPORT ^

AUTHOR ^

Stefan Geneshky - minimal <at> cpan.org

CONTRIBUTORS ^

Ruslan Zakirov

Julio Fraire

Maurice Aubrey

David Steinbrunner

Gurunandan Bhat

LICENSE ^

This module and all the modules in this package are governed by the same license as Perl itself.

syntax highlighting: