1 package Catalyst::Plugin::Static::Simple;
3 use namespace::autoclean;
8 use Catalyst::Plugin::Static::Simple::Middleware;
10 our $VERSION = '0.32';
12 before setup_finalize => sub {
16 = $app->config->{'Plugin::Static::Simple'}
17 = $app->config->{'static'}
18 = Catalyst::Utils::merge_hashes(
19 $app->config->{'Plugin::Static::Simple'} || {},
20 $app->config->{static} || {}
23 $config->{dirs} ||= [];
24 $config->{include_path} ||= [ $app->config->{root} ];
25 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
26 $config->{ignore_dirs} ||= [];
27 $config->{debug} ||= $app->debug;
29 my $static_middleware = Catalyst::Plugin::Static::Simple::Middleware->new({
31 cat_app => ref($app) || $app,
32 content_type => $app->_build_content_type_callback,
35 $app->setup_middleware( $static_middleware );
38 sub _build_content_type_callback {
41 my $config = $c->config->{'Plugin::Static::Simple'};
43 my $full_path = shift;
46 if ( $config->{mime_types} && $full_path =~ /.*\.(\S{1,})$/xms ) {
47 $mime_type = $config->{mime_types}->{ $1 };
50 return $mime_type || Plack::MIME->mime_type($full_path) || 'text/plain';
54 sub serve_static_file {
55 my ( $c, $full_path ) = @_;
59 if(! -f $full_path ) {
60 $res = Catalyst::Plugin::Static::Simple::Middleware->return_404;
62 my $file_app = Plack::App::File->new( {
64 content_type => $c->_build_content_type_callback
66 $res = $file_app->call($c->req->env);
69 $c->res->from_psgi_response($res);
78 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
83 use Catalyst qw/ Static::Simple /;
85 # that's it; static content is automatically served by Catalyst
86 # from the application's root directory, though you can configure
87 # things or bypass Catalyst entirely in a production environment
89 # one caveat: the files must be served from an absolute path
90 # (i.e. /images/foo.png)
94 The Static::Simple plugin is designed to make serving static content in
95 your application during development quick and easy, without requiring a
96 single line of code from you.
98 This plugin detects static files by looking at the file extension in the
99 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
100 lightweight L<MIME::Types> module to map file extensions to
101 IANA-registered MIME types, and will serve your static files with the
102 correct MIME type directly to the browser, without being processed
105 Note that actions mapped to paths using periods (.) will still operate
108 If the plugin can not find the file, the request is dispatched to your
109 application instead. This means you are responsible for generating a
110 C<404> error if your applicaton can not process the request:
112 # handled by static::simple, not dispatched to your application
115 # static::simple will not find the file and let your application
116 # handle the request. You are responsible for generating a file
117 # or returning a 404 error
118 /images/does_not_exist.png
120 Though Static::Simple is designed to work out-of-the-box, you can tweak
121 the operation by adding various configuration options. In a production
122 environment, you will probably want to use your webserver to deliver
123 static content; for an example see L<USING WITH APACHE>, below.
125 =head1 DEFAULT BEHAVIOUR
127 By default, Static::Simple will deliver all files having extensions
128 (that is, bits of text following a period (C<.>)), I<except> files
129 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
130 C<xhtml>. These files, and all files without extensions, will be
131 processed through Catalyst. If L<MIME::Types> doesn't recognize an
132 extension, it will be served as C<text/plain>.
134 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
135 and C<xhtml> I<will not> be served statically by default, they will be
136 processed by Catalyst. Thus if you want to use C<.html> files from
137 within a Catalyst app as static files, you need to change the
138 configuration of Static::Simple. Note also that files having any other
139 extension I<will> be served statically, so if you're using any other
140 extension for template files, you should also change the configuration.
142 Logging of static files is turned off by default.
144 =head1 ADVANCED CONFIGURATION
146 Configuration is completely optional and is specified within
147 C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}>. If you use any of these options,
148 this module will probably feel less "simple" to you!
150 =head2 Enabling request logging
152 Since Catalyst 5.50, logging of static requests is turned off by
153 default; static requests tend to clutter the log output and rarely
154 reveal anything useful. However, if you want to enable logging of static
155 requests, you can do so by setting
156 C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}-E<gt>{logging}> to 1.
158 =head2 Forcing directories into static mode
160 Define a list of top-level directories beneath your 'root' directory
161 that should always be served in static mode. Regular expressions may be
162 specified using C<qr//>.
165 'Plugin::Static::Simple' => {
173 =head2 Including additional directories
175 You may specify a list of directories in which to search for your static
176 files. The directories will be searched in order and will return the
177 first file found. Note that your root directory is B<not> automatically
178 added to the search path when you specify an C<include_path>. You should
179 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
182 'Plugin::Static::Simple' => {
186 MyApp->config->{root},
191 With the above setting, a request for the file C</images/logo.jpg> will search
192 for the following files, returning the first one found:
194 /path/to/overlay/images/logo.jpg
195 /dynamic/path/images/logo.jpg
196 /your/app/home/root/images/logo.jpg
198 The include path can contain a subroutine reference to dynamically return a
199 list of available directories. This method will receive the C<$c> object as a
200 parameter and should return a reference to a list of directories. Errors can
201 be reported using C<die()>. This method will be called every time a file is
202 requested that appears to be a static file (i.e. it has an extension).
206 sub incpath_generator {
209 if ( $c->session->{customer_dir} ) {
210 return [ $c->session->{customer_dir} ];
212 die "No customer dir defined.";
216 =head2 Ignoring certain types of files
218 There are some file types you may not wish to serve as static files.
219 Most important in this category are your raw template files. By
220 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
221 C<xhtml> will be ignored by Static::Simple in the interest of security.
222 If you wish to define your own extensions to ignore, use the
223 C<ignore_extensions> option:
226 'Plugin::Static::Simple' => {
227 ignore_extensions => [ qw/html asp php/ ],
231 =head2 Ignoring entire directories
233 To prevent an entire directory from being served statically, you can use
234 the C<ignore_dirs> option. This option contains a list of relative
235 directory paths to ignore. If using C<include_path>, the path will be
236 checked against every included path.
239 'Plugin::Static::Simple' => {
240 ignore_dirs => [ qw/tmpl css/ ],
244 For example, if combined with the above C<include_path> setting, this
245 C<ignore_dirs> value will ignore the following directories if they exist:
247 /path/to/overlay/tmpl
251 /your/app/home/root/tmpl
252 /your/app/home/root/css
254 =head2 Custom MIME types
256 To override or add to the default MIME types set by the L<MIME::Types>
257 module, you may enter your own extension to MIME type mapping.
260 'Plugin::Static::Simple' => {
268 =head2 Controlling caching with Expires header
270 The files served by Static::Simple will have a Last-Modified header set,
271 which allows some browsers to cache them for a while. However if you want
272 to explicitly set an Expires header, such as to allow proxies to cache your
273 static content, then you can do so by setting the "expires" config option.
275 The value indicates the number of seconds after access time to allow caching.
276 So a value of zero really means "don't cache at all", and any higher values
277 will keep the file around for that long.
280 'Plugin::Static::Simple' => {
281 expires => 3600, # Caching allowed for one hour.
285 =head2 Compatibility with other plugins
287 Since version 0.12, Static::Simple plays nice with other plugins. It no
288 longer short-circuits the C<prepare_action> stage as it was causing too
289 many compatibility issues with other plugins.
291 =head2 Debugging information
293 Enable additional debugging information printed in the Catalyst log. This
294 is automatically enabled when running Catalyst in -Debug mode.
297 'Plugin::Static::Simple' => {
302 =head1 USING WITH APACHE
304 While Static::Simple will work just fine serving files through Catalyst
305 in mod_perl, for increased performance you may wish to have Apache
306 handle the serving of your static files directly. To do this, simply use
307 a dedicated directory for your static files and configure an Apache
308 Location block for that directory This approach is recommended for
309 production installations.
311 <Location /myapp/static>
312 SetHandler default-handler
315 Using this approach Apache will bypass any handling of these directories
316 through Catalyst. You can leave Static::Simple as part of your
317 application, and it will continue to function on a development server,
318 or using Catalyst's built-in server.
320 In practice, your Catalyst application is probably (i.e. should be)
321 structured in the recommended way (i.e., that generated by bootstrapping
322 the application with the C<catalyst.pl> script, with a main directory
323 under which is a C<lib/> directory for module files and a C<root/>
324 directory for templates and static files). Thus, unless you break up
325 this structure when deploying your app by moving the static files to a
326 different location in your filesystem, you will need to use an Alias
327 directive in Apache to point to the right place. You will then need to
328 add a Directory block to give permission for Apache to serve these
329 files. The final configuration will look something like this:
331 Alias /myapp/static /filesystem/path/to/MyApp/root/static
332 <Directory /filesystem/path/to/MyApp/root/static>
335 <Location /myapp/static>
336 SetHandler default-handler
339 If you are running in a VirtualHost, you can just set the DocumentRoot
340 location to the location of your root directory; see
341 L<Catalyst::Engine::Apache2::MP20>.
343 =head1 PUBLIC METHODS
345 =head2 serve_static_file $file_path
347 Will serve the file located in $file_path statically. This is useful when
348 you need to autogenerate them if they don't exist, or they are stored in a model.
350 package MyApp::Controller::User;
352 sub curr_user_thumb : PathPart("my_thumbnail.png") {
353 my ( $self, $c ) = @_;
354 my $file_path = $c->user->picture_thumbnail_path;
355 $c->serve_static_file($file_path);
358 =head1 INTERNAL EXTENDED METHODS
360 Static::Simple extends the following steps in the Catalyst process.
362 =head2 prepare_action
364 C<prepare_action> is used to first check if the request path is a static
365 file. If so, we skip all other C<prepare_action> steps to improve
370 C<dispatch> takes the file found during C<prepare_action> and writes it
375 C<finalize> serves up final header information and displays any log
380 C<setup> initializes all default values.
384 L<Catalyst>, L<Catalyst::Plugin::Static>,
385 L<http://www.iana.org/assignments/media-types/>
389 Andy Grundman, <andy@hybridized.org>
393 Marcus Ramberg, <mramberg@cpan.org>
395 Jesse Sheidlower, <jester@panix.com>
397 Guillermo Roditi, <groditi@cpan.org>
399 Florian Ragwitz, <rafl@debian.org>
401 Tomas Doran, <bobtfish@bobtfish.net>
405 Matt S Trout, <mst@shadowcat.co.uk>
407 Toby Corkindale, <tjc@wintrmute.net>
409 Graeme Lawton <cpan@per.ly>
411 Mark Ellis <markellis@cpan.org>
415 The authors of Catalyst::Plugin::Static:
421 For the include_path code from Template Toolkit:
427 Copyright (c) 2005 - 2011
428 the Catalyst::Plugin::Static::Simple L</AUTHOR> and L</CONTRIBUTORS>
433 This program is free software, you can redistribute it and/or modify it under
434 the same terms as Perl itself.