1 package Catalyst::Plugin::Static::Simple;
4 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
10 our $VERSION = '0.09';
12 __PACKAGE__->mk_classdata( qw/_static_mime_types/ );
13 __PACKAGE__->mk_accessors( qw/_static_file
15 _static_debug_message/ );
17 # prepare_action is used to first check if the request path is a static file.
18 # If so, we skip all other prepare_action steps to improve performance.
21 my $path = $c->req->path;
23 # is the URI in a static-defined path?
24 foreach my $dir ( @{ $c->config->{static}->{dirs} } ) {
25 my $re = ( $dir =~ /^qr\//xms ) ? eval $dir : qr/^${dir}/;
27 $c->error( "Error compiling static dir regex '$dir': $@" );
30 if ( $c->_locate_static_file ) {
31 $c->_debug_msg( "from static directory" )
32 if ( $c->config->{static}->{debug} );
35 $c->_debug_msg( "404: file not found: $path" )
36 if ( $c->config->{static}->{debug} );
37 $c->res->status( 404 );
43 # Does the path have an extension?
44 if ( $path =~ /.*\.(\S{1,})$/xms ) {
46 return if ( $c->_locate_static_file );
49 return $c->NEXT::ACTUAL::prepare_action(@_);
52 # dispatch takes the file found during prepare_action and serves it
56 return if ( $c->res->status != 200 );
58 if ( $c->_static_file ) {
59 if ( $c->config->{static}->{no_logs} && $c->log->can('abort') ) {
62 return $c->_serve_static;
65 return $c->NEXT::ACTUAL::dispatch(@_);
69 # finalize serves up final header information
73 # display all log messages
74 if ( $c->config->{static}->{debug} && scalar @{$c->_debug_msg} ) {
75 $c->log->debug( "Static::Simple: " .
76 join( " ", @{$c->_debug_msg} ) );
79 # return DECLINED when under mod_perl
80 if ( $c->config->{static}->{use_apache} && $c->_static_apache_mode ) {
81 my $engine = $c->_static_apache_mode;
83 if ( $engine == 13 ) {
84 return Apache::Constants::DECLINED;
86 elsif ( $engine == 19 ) {
87 return Apache::Const::DECLINED;
89 elsif ( $engine == 20 ) {
90 return Apache2::Const::DECLINED;
94 if ( $c->res->status =~ /^(1\d\d|[23]04)$/xms ) {
95 $c->res->headers->remove_content_headers;
96 return $c->finalize_headers;
99 return $c->NEXT::ACTUAL::finalize(@_);
107 $c->config->{static}->{dirs} ||= [];
108 $c->config->{static}->{include_path} ||= [ $c->config->{root} ];
109 $c->config->{static}->{mime_types} ||= {};
110 $c->config->{static}->{ignore_extensions} ||= [ qw/tt html xhtml/ ];
111 $c->config->{static}->{ignore_dirs} ||= [];
112 $c->config->{static}->{use_apache} ||= 0;
113 $c->config->{static}->{debug} ||= $c->debug;
114 if ( ! defined $c->config->{static}->{no_logs} ) {
115 $c->config->{static}->{no_logs} = 1;
118 # load up a MIME::Types object, only loading types with
119 # at least 1 file extension
120 $c->_static_mime_types( MIME::Types->new( only_complete => 1 ) );
122 # preload the type index hash so it's not built on the first request
123 $c->_static_mime_types->create_type_index;
126 # Search through all included directories for the static file
127 # Based on Template Toolkit INCLUDE_PATH code
128 sub _locate_static_file {
131 my $path = $c->req->path;
133 my @ipaths = @{ $c->config->{static}->{include_path} };
135 my $count = 64; # maximum number of directories to search
138 while ( @ipaths && --$count) {
139 my $dir = shift @ipaths || next DIR_CHECK;
141 if ( ref $dir eq 'CODE' ) {
142 eval { $dpaths = &$dir( $c ) };
144 $c->log->error( "Static::Simple: include_path error: " . $@ );
146 unshift( @ipaths, @$dpaths );
151 if ( -d $dir && -f $dir . '/' . $path ) {
153 # do we need to ignore the file?
154 for my $ignore ( @{ $c->config->{static}->{ignore_dirs} } ) {
156 if ( $path =~ /^$ignore\// ) {
157 $c->_debug_msg( "Ignoring directory `$ignore`" )
158 if ( $c->config->{static}->{debug} );
163 # do we need to ignore based on extension?
165 ( @{ $c->config->{static}->{ignore_extensions} } ) {
166 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
167 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
168 if ( $c->config->{static}->{debug} );
173 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
174 if ( $c->config->{static}->{debug} );
175 return $c->_static_file( $dir . '/' . $path );
186 my $path = $c->req->path;
188 # abort if running under mod_perl
189 # note that we do not use the Apache method if the user has defined
190 # custom MIME types or is using include paths, as Apache would not know
194 if ( $c->config->{static}->{use_apache} ) {
195 # check engine version
196 last APACHE_CHECK unless $c->engine =~ /Apache::MP(\d{2})/xms;
199 # skip if we have user-defined MIME types
200 last APACHE_CHECK if keys %{ $c->config->{static}->{mime_types} };
202 # skip if the file is in a user-defined include path
203 last APACHE_CHECK if $c->_static_file
204 ne $c->config->{root} . '/' . $path;
206 # check that Apache will serve the correct file
207 if ( $c->apache->document_root ne $c->config->{root} ) {
208 $c->log->warn( 'Static::Simple: Your Apache DocumentRoot'
209 . ' must be set to ' . $c->config->{root}
210 . ' to use the Apache feature. Yours is'
211 . ' currently ' . $c->apache->document_root
215 $c->_debug_msg( 'DECLINED to Apache' )
216 if ( $c->config->{static}->{debug} );
217 $c->_static_apache_mode( $engine );
223 my $type = $c->_ext_to_type;
225 my $full_path = $c->_static_file;
226 my $stat = stat( $full_path );
228 # the below code all from C::P::Static
229 if ( $c->req->headers->if_modified_since ) {
230 if ( $c->req->headers->if_modified_since == $stat->mtime ) {
231 $c->res->status( 304 ); # Not Modified
232 $c->res->headers->remove_content_headers;
237 my $content = read_file( $full_path );
238 $c->res->headers->content_type( $type );
239 $c->res->headers->content_length( $stat->size );
240 $c->res->headers->last_modified( $stat->mtime );
241 $c->res->output( $content );
245 # looks up the correct MIME type for the current file extension
248 my $path = $c->req->path;
250 if ( $path =~ /.*\.(\S{1,})$/xms ) {
252 my $user_types = $c->config->{static}->{mime_types};
253 my $type = $user_types->{$ext}
254 || $c->_static_mime_types->mimeTypeOf( $ext );
256 $c->_debug_msg( "as $type" )
257 if ( $c->config->{static}->{debug} );
261 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
262 if ( $c->config->{static}->{debug} );
267 $c->_debug_msg( 'as text/plain (no extension)' )
268 if ( $c->config->{static}->{debug} );
274 my ( $c, $msg ) = @_;
276 if ( !defined $c->_static_debug_message ) {
277 $c->_static_debug_message( [] );
281 push @{ $c->_static_debug_message }, $msg;
284 return $c->_static_debug_message;
292 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
297 MyApp->setup( qw/Static::Simple/ );
301 The Static::Simple plugin is designed to make serving static content in your
302 application during development quick and easy, without requiring a single
303 line of code from you.
305 It will detect static files used in your application by looking for file
306 extensions in the URI. By default, you can simply load this plugin and it
307 will immediately begin serving your static files with the correct MIME type.
308 The light-weight MIME::Types module is used to map file extensions to
309 IANA-registered MIME types.
311 Note that actions mapped to paths using periods (.) will still operate
314 You may further tweak the operation by adding configuration options, described
317 =head1 ADVANCED CONFIGURATION
319 Configuration is completely optional and is specified within
320 MyApp->config->{static}. If you use any of these options, the module will
321 probably feel less "simple" to you!
323 =head2 Aborting request logging
325 Since Catalyst 5.50, there has been added support for dropping logging for a
326 request. This is enabled by default for static files, as static requests tend
327 to clutter the log output. However, if you want logging of static requests,
328 you can enable it by setting MyApp->config->{static}->{no_logs} to 0.
330 =head2 Forcing directories into static mode
332 Define a list of top-level directories beneath your 'root' directory that
333 should always be served in static mode. Regular expressions may be
334 specified using qr//.
336 MyApp->config->{static}->{dirs} = [
341 =head2 Including additional directories
343 You may specify a list of directories in which to search for your static
344 files. The directories will be searched in order and will return the first
345 file found. Note that your root directory is B<not> automatically added to
346 the search path when you specify an include_path. You should use
347 MyApp->config->{root} to add it.
349 MyApp->config->{static}->{include_path} = [
352 MyApp->config->{root}
355 With the above setting, a request for the file /images/logo.jpg will search
356 for the following files, returning the first one found:
358 /path/to/overlay/images/logo.jpg
359 /dynamic/path/images/logo.jpg
360 /your/app/home/root/images/logo.jpg
362 The include path can contain a subroutine reference to dynamically return a
363 list of available directories. This method will receive the $c object as a
364 parameter and should return a reference to a list of directories. Errors can
365 be reported using die(). This method will be called every time a file is
366 requested that appears to be a static file (i.e. it has an extension).
370 sub incpath_generator {
373 if ( $c->session->{customer_dir} ) {
374 return [ $c->session->{customer_dir} ];
376 die "No customer dir defined.";
380 =head2 Ignoring certain types of files
382 There are some file types you may not wish to serve as static files. Most
383 important in this category are your raw template files. By default, files
384 with the extensions tt, html, and xhtml will be ignored by Static::Simple in
385 the interest of security. If you wish to define your own extensions to
386 ignore, use the ignore_extensions option:
388 MyApp->config->{static}->{ignore_extensions} = [ qw/tt html xhtml/ ];
390 =head2 Ignoring entire directories
392 To prevent an entire directory from being served statically, you can use the
393 ignore_dirs option. This option contains a list of relative directory paths
394 to ignore. If using include_path, the path will be checked against every
397 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
399 For example, if combined with the above include_path setting, this
400 ignore_dirs value will ignore the following directories if they exist:
402 /path/to/overlay/tmpl
406 /your/app/home/root/tmpl
407 /your/app/home/root/css
409 =head2 Custom MIME types
411 To override or add to the default MIME types set by the MIME::Types module,
412 you may enter your own extension to MIME type mapping.
414 MyApp->config->{static}->{mime_types} = {
419 =head2 Apache integration and performance
421 Optionally, when running under mod_perl, Static::Simple can return DECLINED
422 on static files to allow Apache to serve the file. A check is first done to
423 make sure that Apache's DocumentRoot matches your Catalyst root, and that you
424 are not using any custom MIME types or multiple roots. To enable the Apache
425 support, you can set the following option.
427 MyApp->config->{static}->{use_apache} = 1;
429 By default this option is disabled because after several benchmarks it
430 appears that just serving the file from Catalyst is the better option. On a
431 3K file, Catalyst appears to be around 25% faster, and is 42% faster on a 10K
432 file. My benchmarking was done using the following 'siege' command, so other
433 benchmarks would be welcome!
435 siege -u http://server/static/css/10K.css -b -t 1M -c 1
437 For best static performance, you should still serve your static files directly
438 from Apache by defining a Location block similar to the following:
441 SetHandler default-handler
444 =head2 Bypassing other plugins
446 This plugin checks for a static file in the prepare_action stage. If the
447 request is for a static file, it will bypass all remaining prepare_action
448 steps. This means that by placing Static::Simple before all other plugins,
449 they will not execute when a static file is found. This can be helpful by
450 skipping session cookie checks for example. Or, if you want some plugins
451 to run even on static files, list them before Static::Simple.
453 Currently, work done by plugins in any other prepare method will execute
456 =head2 Debugging information
458 Enable additional debugging information printed in the Catalyst log. This
459 is automatically enabled when running Catalyst in -Debug mode.
461 MyApp->config->{static}->{debug} = 1;
465 L<Catalyst>, L<Catalyst::Plugin::Static>,
466 L<http://www.iana.org/assignments/media-types/>
470 Andy Grundman, <andy@hybridized.org>
474 Marcus Ramberg, <mramberg@cpan.org>
478 The authors of Catalyst::Plugin::Static:
484 For the include_path code from Template Toolkit:
490 This program is free software, you can redistribute it and/or modify it under
491 the same terms as Perl itself.