NAME

Catalyst::Plugin::EnableMiddleware - Enable Plack Middleware via Configuration

SYNOPSIS

    package MyApp::Web;

    our $VERSION = '0.01';

    use Moose;
    use Catalyst qw/EnableMiddleware/;
    use Plack::Middleware::StackTrace;

    extends 'Catalyst';

    my $stacktrace_middleware = Plack::Middleware::StackTrace->new;

    __PACKAGE__->config(
      'Plugin::EnableMiddleware', [
        'Debug',
        '+MyApp::Custom',
        $stacktrace_middleware,
        'Session' => {store => 'File'},
        sub {
          my $app = shift;
          return sub {
            my $env = shift;
            $env->{myapp.customkey} = 'helloworld';
            $app->($env);
          },
        },
      ],
    );

    __PACKAGE__->setup;
    __PACKAGE__->meta->make_immutable;

DESCRIPTION

Modern versions of Catalyst use Plack as the underlying engine to connect your application to an http server. This means that you can take advantage of the full Plack software ecosystem to grow your application and to better componentize and re-use your code.

Middleware is a large part of this ecosystem. Plack::Middleware wraps your PSGI application with additional functionality, such as adding Sessions ( as in Plack::Middleware::Session), Debugging (as in Plack::Middleware::Debug) and logging (as in Plack::Middleware::LogDispatch or Plack::Middleware::Log4Perl).

Generally you can enable middleware in your psgi file, as in the following example

    #!/usr/bin/env plackup

    use strict;
    use warnings;

    use MyApp::Web;  ## Your subclass of 'Catalyst'
    use Plack::Builder;

    builder {

      enable 'Debug';
      enable 'Session', store => 'File';

      mount '/' => MyApp::Web->psgi_app;

    };

Here we are using our psgi file and tools that come with Plack in order to enable Plack::Middleware::Debug and Plack::Middleware::Session. This is a nice, clean approach that cleanly separates your Catalyst application from enabled middleware.

However there may be cases when you'd rather enable middleware via you Catalyst application, rather in a stand alone file. For example, you may wish to let your Catalyst application have control over the middleware configuration.

This plugin lets you enable Plack middleware via configuration. For example, the above mapping could be re-written as follows:

    package MyApp::Web;
    our $VERSION = '0.01';

    use Moose;
    use Catalyst qw/EnableMiddleware/;

    extends 'Catalyst';

    __PACKAGE__->config(
      'Plugin::EnableMiddleware', [
        'Debug',
        'Session' => {store => 'File'},
      ]);

    __PACKAGE__->setup;
    __PACKAGE__->meta->make_immutable;

Then your myapp_web.psgi would simply become:

    #!/usr/bin/env plackup

    use strict;
    use warnings;

    use MyApp::Web;  ## Your subclass of 'Catalyst'
    MyApp::Web->psgi_app;

You can of course use a configuration file and format (like Config::General) instead of hard coding your configuration into the main application class. This would allow you the ability to configure things differently in different environments (one of the key reasons to take this approach).

The approach isn't 'either/or' and merits to each are apparent. Choosing one doesn't preclude the other.

CONFIGURATION

Configuration for this plugin should be a ArrayRef under the top level key Plugin::EnableMiddleware, as in the following:

    __PACKAGE__->config(
      'Plugin::EnableMiddleware', \@middleware);

Where @middleware is one or more of the following, applied in the REVERSE of the order listed (to make it function similarly to Plack::Builder:

Middleware Object

An already initialized object that conforms to the Plack::Middleware specification:

    my $stacktrace_middleware = Plack::Middleware::StackTrace->new;

    __PACKAGE__->config(
      'Plugin::EnableMiddleware', [
        $stacktrace_middleware,
      ]);

coderef

A coderef that is an inlined middleware:

    __PACKAGE__->config(
      'Plugin::EnableMiddleware', [
        sub {
          my $app = shift;
          return sub {
            my $env = shift;
            if($env->{PATH_INFO} =~m/forced/) {
              Plack::App::File
                ->new(file=>TestApp->path_to(qw/share static forced.txt/))
                ->call($env);
            } else {
              return $app->($env);
            }
         },
      },
    ]);

a scalar

We assume the scalar refers to a namespace after normalizing it in the same way that Plack::Builder does (it assumes we want something under the 'Plack::Middleware' unless prefixed with a +).

    __PACKAGE__->config(
      'Plugin::EnableMiddleware', [
        'Debug',  ## 'Plack::Middleware::Debug->wrap(...)'
        '+MyApp::Custom',  ## 'MyApp::Custom->wrap(...)'
      ],
    );

a scalar followed by a hashref

Just like the previous, except the following HashRef is used as arguments to initialize the middleware object.

    __PACKAGE__->config(
      'Plugin::EnableMiddleware', [
         'Session' => {store => 'File'},
    ]);

VERSION NOTES

Versions prior to 0.006 applied middleware in the order lists. This led to unexpected problems when porting over middleware from Plack::Builder since that applies middleware in reverse order. This change makes this plugin behave as you might expect.

AUTHOR

John Napiorkowski email:jjnapiork@cpan.org

SEE ALSO

Plack, Plack::Middleware, Catalyst

COPYRIGHT & LICENSE

Copyright 2012, John Napiorkowski email:jjnapiork@cpan.org

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

cpanm Catalyst::Plugin::EnableMiddleware

perl -MCPAN -e shell
install Catalyst::Plugin::EnableMiddleware