1 package Catalyst::Plugin::Static::Simple;
8 use MooseX::Types::Moose qw/ArrayRef Str/;
9 use namespace::autoclean;
11 our $VERSION = '0.30';
13 has _static_file => ( is => 'rw' );
14 has _static_debug_message => ( is => 'rw', isa => ArrayRef[Str] );
16 before prepare_action => sub {
18 my $path = $c->req->path;
19 my $config = $c->config->{static};
21 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
23 # is the URI in a static-defined path?
24 foreach my $dir ( @{ $config->{dirs} } ) {
25 my $dir_re = quotemeta $dir;
27 # strip trailing slashes, they'll be added in our regex
32 if ( $dir =~ m{^qr/}xms ) {
36 $c->error( "Error compiling static dir regex '$dir': $@" );
40 $re = qr{^${dir_re}/};
44 if ( $c->_locate_static_file( $path, 1 ) ) {
45 $c->_debug_msg( 'from static directory' )
48 $c->_debug_msg( "404: file not found: $path" )
50 $c->res->status( 404 );
51 $c->res->content_type( 'text/html' );
56 # Does the path have an extension?
57 if ( $path =~ /.*\.(\S{1,})$/xms ) {
59 $c->_locate_static_file( $path );
63 around dispatch => sub {
67 return if ( $c->res->status != 200 );
69 if ( $c->_static_file ) {
70 if ( $c->config->{static}{no_logs} && $c->log->can('abort') ) {
73 return $c->_serve_static;
80 before finalize => sub {
83 # display all log messages
84 if ( $c->config->{static}{debug} && scalar @{$c->_debug_msg} ) {
85 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
89 before setup_finalize => sub {
92 my $config = $c->config->{static} ||= {};
94 $config->{dirs} ||= [];
95 $config->{include_path} ||= [ $c->config->{root} ];
96 $config->{mime_types} ||= {};
97 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
98 $config->{ignore_dirs} ||= [];
99 $config->{debug} ||= $c->debug;
100 $config->{no_logs} = 1 unless defined $config->{no_logs};
101 $config->{no_logs} = 0 if $config->{logging};
103 # load up a MIME::Types object, only loading types with
104 # at least 1 file extension
105 $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
107 # preload the type index hash so it's not built on the first request
108 $config->{mime_types_obj}->create_type_index;
111 # Search through all included directories for the static file
112 # Based on Template Toolkit INCLUDE_PATH code
113 sub _locate_static_file {
114 my ( $c, $path, $in_static_dir ) = @_;
116 $path = File::Spec->catdir(
117 File::Spec->no_upwards( File::Spec->splitdir( $path ) )
120 my $config = $c->config->{static};
121 my @ipaths = @{ $config->{include_path} };
123 my $count = 64; # maximum number of directories to search
126 while ( @ipaths && --$count) {
127 my $dir = shift @ipaths || next DIR_CHECK;
129 if ( ref $dir eq 'CODE' ) {
130 eval { $dpaths = &$dir( $c ) };
132 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
134 unshift @ipaths, @$dpaths;
138 $dir =~ s/(\/|\\)$//xms;
139 if ( -d $dir && -f $dir . '/' . $path ) {
141 # Don't ignore any files in static dirs defined with 'dirs'
142 unless ( $in_static_dir ) {
143 # do we need to ignore the file?
144 for my $ignore ( @{ $config->{ignore_dirs} } ) {
145 $ignore =~ s{(/|\\)$}{};
146 if ( $path =~ /^$ignore(\/|\\)/ ) {
147 $c->_debug_msg( "Ignoring directory `$ignore`" )
153 # do we need to ignore based on extension?
154 for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
155 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
156 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
163 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
165 return $c->_static_file( $dir . '/' . $path );
175 my $config = $c->config->{static} ||= {};
177 my $full_path = shift || $c->_static_file;
178 my $type = $c->_ext_to_type( $full_path );
179 my $stat = stat $full_path;
181 $c->res->headers->content_type( $type );
182 $c->res->headers->content_length( $stat->size );
183 $c->res->headers->last_modified( $stat->mtime );
184 # Tell Firefox & friends its OK to cache, even over SSL:
185 $c->res->headers->header('Cache-control' => 'public');
186 # Optionally, set a fixed expiry time:
187 if ($config->{expires}) {
188 $c->res->headers->expires(time() + $config->{expires});
191 my $fh = IO::File->new( $full_path, 'r' );
194 $c->res->body( $fh );
197 Catalyst::Exception->throw(
198 message => "Unable to open $full_path for reading" );
204 sub serve_static_file {
205 my ( $c, $full_path ) = @_;
207 my $config = $c->config->{static} ||= {};
209 if ( -e $full_path ) {
210 $c->_debug_msg( "Serving static file: $full_path" )
214 $c->_debug_msg( "404: file not found: $full_path" )
216 $c->res->status( 404 );
217 $c->res->content_type( 'text/html' );
221 $c->_serve_static( $full_path );
224 # looks up the correct MIME type for the current file extension
226 my ( $c, $full_path ) = @_;
228 my $config = $c->config->{static};
230 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
232 my $type = $config->{mime_types}{$ext}
233 || $config->{mime_types_obj}->mimeTypeOf( $ext );
235 $c->_debug_msg( "as $type" ) if $config->{debug};
236 return ( ref $type ) ? $type->type : $type;
239 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
245 $c->_debug_msg( 'as text/plain (no extension)' )
252 my ( $c, $msg ) = @_;
254 if ( !defined $c->_static_debug_message ) {
255 $c->_static_debug_message( [] );
259 push @{ $c->_static_debug_message }, $msg;
262 return $c->_static_debug_message;
270 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
275 use Catalyst qw/ Static::Simple /;
277 # that's it; static content is automatically served by Catalyst
278 # from the application's root directory, though you can configure
279 # things or bypass Catalyst entirely in a production environment
281 # one caveat: the files must be served from an absolute path
282 # (i.e. /images/foo.png)
286 The Static::Simple plugin is designed to make serving static content in
287 your application during development quick and easy, without requiring a
288 single line of code from you.
290 This plugin detects static files by looking at the file extension in the
291 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
292 lightweight L<MIME::Types> module to map file extensions to
293 IANA-registered MIME types, and will serve your static files with the
294 correct MIME type directly to the browser, without being processed
297 Note that actions mapped to paths using periods (.) will still operate
300 If the plugin can not find the file, the request is dispatched to your
301 application instead. This means you are responsible for generating a
302 C<404> error if your applicaton can not process the request:
304 # handled by static::simple, not dispatched to your application
307 # static::simple will not find the file and let your application
308 # handle the request. You are responsible for generating a file
309 # or returning a 404 error
310 /images/does_not_exist.png
312 Though Static::Simple is designed to work out-of-the-box, you can tweak
313 the operation by adding various configuration options. In a production
314 environment, you will probably want to use your webserver to deliver
315 static content; for an example see L<USING WITH APACHE>, below.
317 =head1 DEFAULT BEHAVIOUR
319 By default, Static::Simple will deliver all files having extensions
320 (that is, bits of text following a period (C<.>)), I<except> files
321 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
322 C<xhtml>. These files, and all files without extensions, will be
323 processed through Catalyst. If L<MIME::Types> doesn't recognize an
324 extension, it will be served as C<text/plain>.
326 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
327 and C<xhtml> I<will not> be served statically by default, they will be
328 processed by Catalyst. Thus if you want to use C<.html> files from
329 within a Catalyst app as static files, you need to change the
330 configuration of Static::Simple. Note also that files having any other
331 extension I<will> be served statically, so if you're using any other
332 extension for template files, you should also change the configuration.
334 Logging of static files is turned off by default.
336 =head1 ADVANCED CONFIGURATION
338 Configuration is completely optional and is specified within
339 C<MyApp-E<gt>config-E<gt>{static}>. If you use any of these options,
340 this module will probably feel less "simple" to you!
342 =head2 Enabling request logging
344 Since Catalyst 5.50, logging of static requests is turned off by
345 default; static requests tend to clutter the log output and rarely
346 reveal anything useful. However, if you want to enable logging of static
347 requests, you can do so by setting
348 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{logging}> to 1.
350 =head2 Forcing directories into static mode
352 Define a list of top-level directories beneath your 'root' directory
353 that should always be served in static mode. Regular expressions may be
354 specified using C<qr//>.
365 =head2 Including additional directories
367 You may specify a list of directories in which to search for your static
368 files. The directories will be searched in order and will return the
369 first file found. Note that your root directory is B<not> automatically
370 added to the search path when you specify an C<include_path>. You should
371 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
378 MyApp->config->{root},
383 With the above setting, a request for the file C</images/logo.jpg> will search
384 for the following files, returning the first one found:
386 /path/to/overlay/images/logo.jpg
387 /dynamic/path/images/logo.jpg
388 /your/app/home/root/images/logo.jpg
390 The include path can contain a subroutine reference to dynamically return a
391 list of available directories. This method will receive the C<$c> object as a
392 parameter and should return a reference to a list of directories. Errors can
393 be reported using C<die()>. This method will be called every time a file is
394 requested that appears to be a static file (i.e. it has an extension).
398 sub incpath_generator {
401 if ( $c->session->{customer_dir} ) {
402 return [ $c->session->{customer_dir} ];
404 die "No customer dir defined.";
408 =head2 Ignoring certain types of files
410 There are some file types you may not wish to serve as static files.
411 Most important in this category are your raw template files. By
412 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
413 C<xhtml> will be ignored by Static::Simple in the interest of security.
414 If you wish to define your own extensions to ignore, use the
415 C<ignore_extensions> option:
419 ignore_extensions => [ qw/html asp php/ ],
423 =head2 Ignoring entire directories
425 To prevent an entire directory from being served statically, you can use
426 the C<ignore_dirs> option. This option contains a list of relative
427 directory paths to ignore. If using C<include_path>, the path will be
428 checked against every included path.
432 ignore_dirs => [ qw/tmpl css/ ],
436 For example, if combined with the above C<include_path> setting, this
437 C<ignore_dirs> value will ignore the following directories if they exist:
439 /path/to/overlay/tmpl
443 /your/app/home/root/tmpl
444 /your/app/home/root/css
446 =head2 Custom MIME types
448 To override or add to the default MIME types set by the L<MIME::Types>
449 module, you may enter your own extension to MIME type mapping.
460 =head2 Controlling caching with Expires header
462 The files served by Static::Simple will have a Last-Modified header set,
463 which allows some browsers to cache them for a while. However if you want
464 to explicitly set an Expires header, such as to allow proxies to cache your
465 static content, then you can do so by setting the "expires" config option.
467 The value indicates the number of seconds after access time to allow caching.
468 So a value of zero really means "don't cache at all", and any higher values
469 will keep the file around for that long.
473 expires => 3600, # Caching allowed for one hour.
477 =head2 Compatibility with other plugins
479 Since version 0.12, Static::Simple plays nice with other plugins. It no
480 longer short-circuits the C<prepare_action> stage as it was causing too
481 many compatibility issues with other plugins.
483 =head2 Debugging information
485 Enable additional debugging information printed in the Catalyst log. This
486 is automatically enabled when running Catalyst in -Debug mode.
494 =head1 USING WITH APACHE
496 While Static::Simple will work just fine serving files through Catalyst
497 in mod_perl, for increased performance you may wish to have Apache
498 handle the serving of your static files directly. To do this, simply use
499 a dedicated directory for your static files and configure an Apache
500 Location block for that directory This approach is recommended for
501 production installations.
503 <Location /myapp/static>
504 SetHandler default-handler
507 Using this approach Apache will bypass any handling of these directories
508 through Catalyst. You can leave Static::Simple as part of your
509 application, and it will continue to function on a development server,
510 or using Catalyst's built-in server.
512 In practice, your Catalyst application is probably (i.e. should be)
513 structured in the recommended way (i.e., that generated by bootstrapping
514 the application with the C<catalyst.pl> script, with a main directory
515 under which is a C<lib/> directory for module files and a C<root/>
516 directory for templates and static files). Thus, unless you break up
517 this structure when deploying your app by moving the static files to a
518 different location in your filesystem, you will need to use an Alias
519 directive in Apache to point to the right place. You will then need to
520 add a Directory block to give permission for Apache to serve these
521 files. The final configuration will look something like this:
523 Alias /myapp/static /filesystem/path/to/MyApp/root/static
524 <Directory /filesystem/path/to/MyApp/root/static>
527 <Location /myapp/static>
528 SetHandler default-handler
531 If you are running in a VirtualHost, you can just set the DocumentRoot
532 location to the location of your root directory; see
533 L<Catalyst::Engine::Apache2::MP20>.
535 =head1 PUBLIC METHODS
537 =head2 serve_static_file $file_path
539 Will serve the file located in $file_path statically. This is useful when
540 you need to autogenerate them if they don't exist, or they are stored in a model.
542 package MyApp::Controller::User;
544 sub curr_user_thumb : PathPart("my_thumbnail.png") {
545 my ( $self, $c ) = @_;
546 my $file_path = $c->user->picture_thumbnail_path;
547 $c->serve_static_file($file_path);
550 =head1 INTERNAL EXTENDED METHODS
552 Static::Simple extends the following steps in the Catalyst process.
554 =head2 prepare_action
556 C<prepare_action> is used to first check if the request path is a static
557 file. If so, we skip all other C<prepare_action> steps to improve
562 C<dispatch> takes the file found during C<prepare_action> and writes it
567 C<finalize> serves up final header information and displays any log
572 C<setup> initializes all default values.
576 L<Catalyst>, L<Catalyst::Plugin::Static>,
577 L<http://www.iana.org/assignments/media-types/>
581 Andy Grundman, <andy@hybridized.org>
585 Marcus Ramberg, <mramberg@cpan.org>
587 Jesse Sheidlower, <jester@panix.com>
589 Guillermo Roditi, <groditi@cpan.org>
591 Florian Ragwitz, <rafl@debian.org>
593 Tomas Doran, <bobtfish@bobtfish.net>
597 Matt S Trout, <mst@shadowcat.co.uk>
599 Toby Corkindale, <tjc@wintrmute.net>
603 The authors of Catalyst::Plugin::Static:
609 For the include_path code from Template Toolkit:
615 Copyright (c) 2005 - 2011
616 the Catalyst::Plugin::Static::Simple L</AUTHOR> and L</CONTRIBUTORS>
621 This program is free software, you can redistribute it and/or modify it under
622 the same terms as Perl itself.