1 package Catalyst::Plugin::Static::Simple;
8 use MooseX::Types::Moose qw/ArrayRef Str/;
10 use namespace::autoclean;
12 our $VERSION = '0.30';
14 has _static_file => ( is => 'rw' );
15 has _static_debug_message => ( is => 'rw', isa => ArrayRef[Str] );
17 before prepare_action => sub {
19 my $path = $c->req->path;
20 my $config = $c->config->{'Plugin::Static::Simple'};
22 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
24 # is the URI in a static-defined path?
25 foreach my $dir ( @{ $config->{dirs} } ) {
26 my $dir_re = quotemeta $dir;
28 # strip trailing slashes, they'll be added in our regex
33 if ( $dir =~ m{^qr/}xms ) {
37 $c->error( "Error compiling static dir regex '$dir': $@" );
41 $re = qr{^${dir_re}/};
45 if ( $c->_locate_static_file( $path, 1 ) ) {
46 $c->_debug_msg( 'from static directory' )
49 $c->_debug_msg( "404: file not found: $path" )
51 $c->res->status( 404 );
52 $c->res->content_type( 'text/html' );
57 # Does the path have an extension?
58 if ( $path =~ /.*\.(\S{1,})$/xms ) {
60 $c->_locate_static_file( $path );
64 around dispatch => sub {
68 return if ( $c->res->status != 200 );
70 if ( $c->_static_file ) {
71 if ( $c->config->{'Plugin::Static::Simple'}->{no_logs} && $c->log->can('abort') ) {
74 return $c->_serve_static;
81 before finalize => sub {
84 # display all log messages
85 if ( $c->config->{'Plugin::Static::Simple'}->{debug} && scalar @{$c->_debug_msg} ) {
86 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
90 before setup_finalize => sub {
93 $c->log->warn("Deprecated 'static' config key used, please use the key 'Plugin::Static::Simple' instead")
94 if exists $c->config->{static};
96 = $c->config->{'Plugin::Static::Simple'}
97 = $c->config->{'static'}
98 = Catalyst::Utils::merge_hashes(
99 $c->config->{'Plugin::Static::Simple'} || {},
100 $c->config->{static} || {}
103 $config->{dirs} ||= [];
104 $config->{include_path} ||= [ $c->config->{root} ];
105 $config->{mime_types} ||= {};
106 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
107 $config->{ignore_dirs} ||= [];
108 $config->{debug} ||= $c->debug;
109 $config->{no_logs} = 1 unless defined $config->{no_logs};
110 $config->{no_logs} = 0 if $config->{logging};
112 # load up a MIME::Types object, only loading types with
113 # at least 1 file extension
114 $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
117 # Search through all included directories for the static file
118 # Based on Template Toolkit INCLUDE_PATH code
119 sub _locate_static_file {
120 my ( $c, $path, $in_static_dir ) = @_;
122 $path = File::Spec->catdir(
123 File::Spec->no_upwards( File::Spec->splitdir( $path ) )
126 my $config = $c->config->{'Plugin::Static::Simple'};
127 my @ipaths = @{ $config->{include_path} };
129 my $count = 64; # maximum number of directories to search
132 while ( @ipaths && --$count) {
133 my $dir = shift @ipaths || next DIR_CHECK;
135 if ( ref $dir eq 'CODE' ) {
136 eval { $dpaths = &$dir( $c ) };
138 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
140 unshift @ipaths, @$dpaths;
144 $dir =~ s/(\/|\\)$//xms;
145 if ( -d $dir && -f $dir . '/' . $path ) {
147 # Don't ignore any files in static dirs defined with 'dirs'
148 unless ( $in_static_dir ) {
149 # do we need to ignore the file?
150 for my $ignore ( @{ $config->{ignore_dirs} } ) {
151 $ignore =~ s{(/|\\)$}{};
152 if ( $path =~ /^$ignore(\/|\\)/ ) {
153 $c->_debug_msg( "Ignoring directory `$ignore`" )
159 # do we need to ignore based on extension?
160 for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
161 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
162 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
169 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
171 return $c->_static_file( $dir . '/' . $path );
181 my $config = $c->config->{'Plugin::Static::Simple'};
183 my $full_path = shift || $c->_static_file;
184 my $type = $c->_ext_to_type( $full_path );
185 my $stat = stat $full_path;
187 $c->res->headers->content_type( $type );
188 $c->res->headers->content_length( $stat->size );
189 $c->res->headers->last_modified( $stat->mtime );
190 # Tell Firefox & friends its OK to cache, even over SSL:
191 $c->res->headers->header('Cache-control' => 'public');
192 # Optionally, set a fixed expiry time:
193 if ($config->{expires}) {
194 $c->res->headers->expires(time() + $config->{expires});
197 my $fh = IO::File->new( $full_path, 'r' );
200 $c->res->body( $fh );
203 Catalyst::Exception->throw(
204 message => "Unable to open $full_path for reading" );
210 sub serve_static_file {
211 my ( $c, $full_path ) = @_;
213 my $config = $c->config->{'Plugin::Static::Simple'};
215 if ( -e $full_path ) {
216 $c->_debug_msg( "Serving static file: $full_path" )
220 $c->_debug_msg( "404: file not found: $full_path" )
222 $c->res->status( 404 );
223 $c->res->content_type( 'text/html' );
227 $c->_serve_static( $full_path );
230 # looks up the correct MIME type for the current file extension
232 my ( $c, $full_path ) = @_;
234 my $config = $c->config->{'Plugin::Static::Simple'};
236 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
238 my $type = $config->{mime_types}{$ext}
239 || $config->{mime_types_obj}->mimeTypeOf( $ext );
241 $c->_debug_msg( "as $type" ) if $config->{debug};
242 return ( ref $type ) ? $type->type : $type;
245 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
251 $c->_debug_msg( 'as text/plain (no extension)' )
258 my ( $c, $msg ) = @_;
260 if ( !defined $c->_static_debug_message ) {
261 $c->_static_debug_message( [] );
265 push @{ $c->_static_debug_message }, $msg;
268 return $c->_static_debug_message;
276 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
281 use Catalyst qw/ Static::Simple /;
283 # that's it; static content is automatically served by Catalyst
284 # from the application's root directory, though you can configure
285 # things or bypass Catalyst entirely in a production environment
287 # one caveat: the files must be served from an absolute path
288 # (i.e. /images/foo.png)
292 The Static::Simple plugin is designed to make serving static content in
293 your application during development quick and easy, without requiring a
294 single line of code from you.
296 This plugin detects static files by looking at the file extension in the
297 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
298 lightweight L<MIME::Types> module to map file extensions to
299 IANA-registered MIME types, and will serve your static files with the
300 correct MIME type directly to the browser, without being processed
303 Note that actions mapped to paths using periods (.) will still operate
306 If the plugin can not find the file, the request is dispatched to your
307 application instead. This means you are responsible for generating a
308 C<404> error if your applicaton can not process the request:
310 # handled by static::simple, not dispatched to your application
313 # static::simple will not find the file and let your application
314 # handle the request. You are responsible for generating a file
315 # or returning a 404 error
316 /images/does_not_exist.png
318 Though Static::Simple is designed to work out-of-the-box, you can tweak
319 the operation by adding various configuration options. In a production
320 environment, you will probably want to use your webserver to deliver
321 static content; for an example see L<USING WITH APACHE>, below.
323 =head1 DEFAULT BEHAVIOUR
325 By default, Static::Simple will deliver all files having extensions
326 (that is, bits of text following a period (C<.>)), I<except> files
327 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
328 C<xhtml>. These files, and all files without extensions, will be
329 processed through Catalyst. If L<MIME::Types> doesn't recognize an
330 extension, it will be served as C<text/plain>.
332 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
333 and C<xhtml> I<will not> be served statically by default, they will be
334 processed by Catalyst. Thus if you want to use C<.html> files from
335 within a Catalyst app as static files, you need to change the
336 configuration of Static::Simple. Note also that files having any other
337 extension I<will> be served statically, so if you're using any other
338 extension for template files, you should also change the configuration.
340 Logging of static files is turned off by default.
342 =head1 ADVANCED CONFIGURATION
344 Configuration is completely optional and is specified within
345 C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}>. If you use any of these options,
346 this module will probably feel less "simple" to you!
348 =head2 Enabling request logging
350 Since Catalyst 5.50, logging of static requests is turned off by
351 default; static requests tend to clutter the log output and rarely
352 reveal anything useful. However, if you want to enable logging of static
353 requests, you can do so by setting
354 C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}-E<gt>{logging}> to 1.
356 =head2 Forcing directories into static mode
358 Define a list of top-level directories beneath your 'root' directory
359 that should always be served in static mode. Regular expressions may be
360 specified using C<qr//>.
363 'Plugin::Static::Simple' => {
371 =head2 Including additional directories
373 You may specify a list of directories in which to search for your static
374 files. The directories will be searched in order and will return the
375 first file found. Note that your root directory is B<not> automatically
376 added to the search path when you specify an C<include_path>. You should
377 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
380 'Plugin::Static::Simple' => {
384 MyApp->config->{root},
389 With the above setting, a request for the file C</images/logo.jpg> will search
390 for the following files, returning the first one found:
392 /path/to/overlay/images/logo.jpg
393 /dynamic/path/images/logo.jpg
394 /your/app/home/root/images/logo.jpg
396 The include path can contain a subroutine reference to dynamically return a
397 list of available directories. This method will receive the C<$c> object as a
398 parameter and should return a reference to a list of directories. Errors can
399 be reported using C<die()>. This method will be called every time a file is
400 requested that appears to be a static file (i.e. it has an extension).
404 sub incpath_generator {
407 if ( $c->session->{customer_dir} ) {
408 return [ $c->session->{customer_dir} ];
410 die "No customer dir defined.";
414 =head2 Ignoring certain types of files
416 There are some file types you may not wish to serve as static files.
417 Most important in this category are your raw template files. By
418 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
419 C<xhtml> will be ignored by Static::Simple in the interest of security.
420 If you wish to define your own extensions to ignore, use the
421 C<ignore_extensions> option:
424 'Plugin::Static::Simple' => {
425 ignore_extensions => [ qw/html asp php/ ],
429 =head2 Ignoring entire directories
431 To prevent an entire directory from being served statically, you can use
432 the C<ignore_dirs> option. This option contains a list of relative
433 directory paths to ignore. If using C<include_path>, the path will be
434 checked against every included path.
437 'Plugin::Static::Simple' => {
438 ignore_dirs => [ qw/tmpl css/ ],
442 For example, if combined with the above C<include_path> setting, this
443 C<ignore_dirs> value will ignore the following directories if they exist:
445 /path/to/overlay/tmpl
449 /your/app/home/root/tmpl
450 /your/app/home/root/css
452 =head2 Custom MIME types
454 To override or add to the default MIME types set by the L<MIME::Types>
455 module, you may enter your own extension to MIME type mapping.
458 'Plugin::Static::Simple' => {
466 =head2 Controlling caching with Expires header
468 The files served by Static::Simple will have a Last-Modified header set,
469 which allows some browsers to cache them for a while. However if you want
470 to explicitly set an Expires header, such as to allow proxies to cache your
471 static content, then you can do so by setting the "expires" config option.
473 The value indicates the number of seconds after access time to allow caching.
474 So a value of zero really means "don't cache at all", and any higher values
475 will keep the file around for that long.
478 'Plugin::Static::Simple' => {
479 expires => 3600, # Caching allowed for one hour.
483 =head2 Compatibility with other plugins
485 Since version 0.12, Static::Simple plays nice with other plugins. It no
486 longer short-circuits the C<prepare_action> stage as it was causing too
487 many compatibility issues with other plugins.
489 =head2 Debugging information
491 Enable additional debugging information printed in the Catalyst log. This
492 is automatically enabled when running Catalyst in -Debug mode.
495 'Plugin::Static::Simple' => {
500 =head1 USING WITH APACHE
502 While Static::Simple will work just fine serving files through Catalyst
503 in mod_perl, for increased performance you may wish to have Apache
504 handle the serving of your static files directly. To do this, simply use
505 a dedicated directory for your static files and configure an Apache
506 Location block for that directory This approach is recommended for
507 production installations.
509 <Location /myapp/static>
510 SetHandler default-handler
513 Using this approach Apache will bypass any handling of these directories
514 through Catalyst. You can leave Static::Simple as part of your
515 application, and it will continue to function on a development server,
516 or using Catalyst's built-in server.
518 In practice, your Catalyst application is probably (i.e. should be)
519 structured in the recommended way (i.e., that generated by bootstrapping
520 the application with the C<catalyst.pl> script, with a main directory
521 under which is a C<lib/> directory for module files and a C<root/>
522 directory for templates and static files). Thus, unless you break up
523 this structure when deploying your app by moving the static files to a
524 different location in your filesystem, you will need to use an Alias
525 directive in Apache to point to the right place. You will then need to
526 add a Directory block to give permission for Apache to serve these
527 files. The final configuration will look something like this:
529 Alias /myapp/static /filesystem/path/to/MyApp/root/static
530 <Directory /filesystem/path/to/MyApp/root/static>
533 <Location /myapp/static>
534 SetHandler default-handler
537 If you are running in a VirtualHost, you can just set the DocumentRoot
538 location to the location of your root directory; see
539 L<Catalyst::Engine::Apache2::MP20>.
541 =head1 PUBLIC METHODS
543 =head2 serve_static_file $file_path
545 Will serve the file located in $file_path statically. This is useful when
546 you need to autogenerate them if they don't exist, or they are stored in a model.
548 package MyApp::Controller::User;
550 sub curr_user_thumb : PathPart("my_thumbnail.png") {
551 my ( $self, $c ) = @_;
552 my $file_path = $c->user->picture_thumbnail_path;
553 $c->serve_static_file($file_path);
556 =head1 INTERNAL EXTENDED METHODS
558 Static::Simple extends the following steps in the Catalyst process.
560 =head2 prepare_action
562 C<prepare_action> is used to first check if the request path is a static
563 file. If so, we skip all other C<prepare_action> steps to improve
568 C<dispatch> takes the file found during C<prepare_action> and writes it
573 C<finalize> serves up final header information and displays any log
578 C<setup> initializes all default values.
582 L<Catalyst>, L<Catalyst::Plugin::Static>,
583 L<http://www.iana.org/assignments/media-types/>
587 Andy Grundman, <andy@hybridized.org>
591 Marcus Ramberg, <mramberg@cpan.org>
593 Jesse Sheidlower, <jester@panix.com>
595 Guillermo Roditi, <groditi@cpan.org>
597 Florian Ragwitz, <rafl@debian.org>
599 Tomas Doran, <bobtfish@bobtfish.net>
603 Matt S Trout, <mst@shadowcat.co.uk>
605 Toby Corkindale, <tjc@wintrmute.net>
609 The authors of Catalyst::Plugin::Static:
615 For the include_path code from Template Toolkit:
621 Copyright (c) 2005 - 2011
622 the Catalyst::Plugin::Static::Simple L</AUTHOR> and L</CONTRIBUTORS>
627 This program is free software, you can redistribute it and/or modify it under
628 the same terms as Perl itself.