Catalyst::Plugin::EnableMiddleware - Enable Plack Middleware via Configuration
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;
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
psgi
#!/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:
myapp_web.psgi
#!/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 for this plugin should be a ArrayRef under the top level key Plugin::EnableMiddleware, as in the following:
Plugin::EnableMiddleware
__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
An already initialized object that conforms to the Plack::Middleware specification:
my $stacktrace_middleware = Plack::Middleware::StackTrace->new; __PACKAGE__->config( 'Plugin::EnableMiddleware', [ $stacktrace_middleware, ]);
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); } }, }, ]);
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(...)' ], );
Just like the previous, except the following HashRef is used as arguments to initialize the middleware object.
HashRef
__PACKAGE__->config( 'Plugin::EnableMiddleware', [ 'Session' => {store => 'File'}, ]);
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.
0.006
John Napiorkowski email:jjnapiork@cpan.org
Plack, Plack::Middleware, Catalyst
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.
3 POD Errors
The following errors were encountered while parsing the POD:
Unknown directive: =over4
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install Catalyst::Plugin::EnableMiddleware, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Catalyst::Plugin::EnableMiddleware
CPAN shell
perl -MCPAN -e shell install Catalyst::Plugin::EnableMiddleware
For more information on module installation, please visit the detailed CPAN module installation guide.