1 package Catalyst::Plugin::Static::Simple;
9 use namespace::autoclean;
11 our $VERSION = '0.37';
13 has _static_file => ( is => 'rw' );
14 has _static_debug_message => ( is => 'rw', isa => 'ArrayRef[Str]' );
16 after setup_finalize => sub {
19 # New: Turn off new 'autoflush' flag in logger (see Catalyst::Log).
20 # This is needed to surpress output of debug log messages for
22 $c->log->autoflush(0) if $c->log->can('autoflush');
25 before prepare_action => sub {
27 my $path = $c->req->path;
28 my $config = $c->config->{'Plugin::Static::Simple'};
30 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
32 # is the URI in a static-defined path?
33 foreach my $dir ( @{ $config->{dirs} } ) {
34 my $dir_re = quotemeta $dir;
36 # strip trailing slashes, they'll be added in our regex
41 if ( $dir =~ m{^qr/}xms ) {
45 $c->error( "Error compiling static dir regex '$dir': $@" );
49 $re = qr{^${dir_re}/};
53 if ( $c->_locate_static_file( $path, 1 ) ) {
54 $c->_debug_msg( 'from static directory' )
57 $c->_debug_msg( "404: file not found: $path" )
59 $c->res->status( 404 );
60 $c->res->content_type( 'text/html' );
65 # Does the path have an extension?
66 if ( $path =~ /\.([^\/\\]+)$/m ) {
68 $c->_locate_static_file( $path );
72 around dispatch => sub {
76 return if ( $c->res->status != 200 );
78 if ( $c->_static_file ) {
79 if ( $c->config->{'Plugin::Static::Simple'}->{no_logs} && $c->log->can('abort') ) {
82 return $c->_serve_static;
89 before finalize => sub {
92 # display all log messages
93 if ( $c->config->{'Plugin::Static::Simple'}->{debug} && scalar @{$c->_debug_msg} ) {
94 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
98 before setup_finalize => sub {
101 $c->log->warn("Deprecated 'static' config key used, please use the key 'Plugin::Static::Simple' instead")
102 if exists $c->config->{static};
104 if (exists $c->config->{static}->{include_path}) {
105 $c->config->{'Plugin::Static::Simple'}->{include_path} = [
106 @{$c->config->{'Plugin::Static::Simple'}->{include_path} || []},
107 @{delete $c->config->{static}->{include_path} || []}
112 = $c->config->{'Plugin::Static::Simple'}
113 = $c->config->{'static'}
114 = Catalyst::Utils::merge_hashes(
115 $c->config->{'Plugin::Static::Simple'} || {},
116 $c->config->{static} || {}
119 $config->{dirs} ||= [];
120 $config->{include_path} ||= [ $c->config->{root} ];
121 $config->{mime_types} ||= {};
122 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
123 $config->{ignore_dirs} ||= [];
124 $config->{debug} ||= $c->debug;
125 $config->{no_logs} = 1 unless defined $config->{no_logs};
126 $config->{no_logs} = 0 if $config->{logging};
128 # load up a MIME::Types object, only loading types with
129 # at least 1 file extension
130 $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
133 # Search through all included directories for the static file
134 # Based on Template Toolkit INCLUDE_PATH code
135 sub _locate_static_file {
136 my ( $c, $path, $in_static_dir ) = @_;
138 $path = File::Spec->catdir(
139 File::Spec->no_upwards( File::Spec->splitdir( $path ) )
142 my $config = $c->config->{'Plugin::Static::Simple'};
143 my @ipaths = @{ $config->{include_path} };
145 my $count = 64; # maximum number of directories to search
148 while ( @ipaths && --$count) {
149 my $dir = shift @ipaths || next DIR_CHECK;
151 if ( ref $dir eq 'CODE' ) {
152 eval { $dpaths = &$dir( $c ) };
154 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
156 unshift @ipaths, @$dpaths;
160 $dir =~ s/(\/|\\)$//xms;
161 if ( -d $dir && -f $dir . '/' . $path ) {
163 # Don't ignore any files in static dirs defined with 'dirs'
164 unless ( $in_static_dir ) {
165 # do we need to ignore the file?
166 for my $ignore ( @{ $config->{ignore_dirs} } ) {
167 $ignore =~ s{(/|\\)$}{};
168 if ( $path =~ /^$ignore(\/|\\)/ ) {
169 $c->_debug_msg( "Ignoring directory `$ignore`" )
175 # do we need to ignore based on extension?
176 for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
177 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
178 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
185 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
187 return $c->_static_file( $dir . '/' . $path );
197 my $config = $c->config->{'Plugin::Static::Simple'};
199 my $full_path = shift || $c->_static_file;
200 my $type = $c->_ext_to_type( $full_path );
201 my $stat = stat $full_path;
203 $c->res->headers->content_type( $type );
204 $c->res->headers->content_length( $stat->size );
205 $c->res->headers->last_modified( $stat->mtime );
206 # Tell Firefox & friends its OK to cache, even over SSL:
207 $c->res->headers->header('Cache-control' => 'public');
208 # Optionally, set a fixed expiry time:
209 if ($config->{expires}) {
210 $c->res->headers->expires(time() + $config->{expires});
213 my $fh = IO::File->new( $full_path, 'r' );
216 $c->res->body( $fh );
219 Catalyst::Exception->throw(
220 message => "Unable to open $full_path for reading" );
226 sub serve_static_file {
227 my ( $c, $full_path ) = @_;
229 my $config = $c->config->{'Plugin::Static::Simple'};
231 if ( -e $full_path ) {
232 $c->_debug_msg( "Serving static file: $full_path" )
236 $c->_debug_msg( "404: file not found: $full_path" )
238 $c->res->status( 404 );
239 $c->res->content_type( 'text/html' );
243 $c->_serve_static( $full_path );
246 # looks up the correct MIME type for the current file extension
248 my ( $c, $full_path ) = @_;
250 my $config = $c->config->{'Plugin::Static::Simple'};
252 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
254 my $type = $config->{mime_types}{$ext}
255 || $config->{mime_types_obj}->mimeTypeOf( $ext );
257 $c->_debug_msg( "as $type" ) if $config->{debug};
258 return ( ref $type ) ? $type->type : $type;
261 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
267 $c->_debug_msg( 'as text/plain (no extension)' )
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 use Catalyst qw/ Static::Simple /;
299 # that's it; static content is automatically served by Catalyst
300 # from the application's root directory, though you can configure
301 # things or bypass Catalyst entirely in a production environment
303 # one caveat: the files must be served from an absolute path
304 # (i.e. /images/foo.png)
308 The Static::Simple plugin is designed to make serving static content in
309 your application during development quick and easy, without requiring a
310 single line of code from you.
312 This plugin detects static files by looking at the file extension in the
313 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
314 lightweight L<MIME::Types> module to map file extensions to
315 IANA-registered MIME types, and will serve your static files with the
316 correct MIME type directly to the browser, without being processed
319 Note that actions mapped to paths using periods (.) will still operate
322 If the plugin can not find the file, the request is dispatched to your
323 application instead. This means you are responsible for generating a
324 C<404> error if your application can not process the request:
326 # handled by static::simple, not dispatched to your application
329 # static::simple will not find the file and let your application
330 # handle the request. You are responsible for generating a file
331 # or returning a 404 error
332 /images/does_not_exist.png
334 Though Static::Simple is designed to work out-of-the-box, you can tweak
335 the operation by adding various configuration options. In a production
336 environment, you will probably want to use your webserver to deliver
337 static content; for an example see L<USING WITH APACHE>, below.
339 =head1 DEFAULT BEHAVIOUR
341 By default, Static::Simple will deliver all files having extensions
342 (that is, bits of text following a period (C<.>)), I<except> files
343 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
344 C<xhtml>. These files, and all files without extensions, will be
345 processed through Catalyst. If L<MIME::Types> doesn't recognize an
346 extension, it will be served as C<text/plain>.
348 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
349 and C<xhtml> I<will not> be served statically by default, they will be
350 processed by Catalyst. Thus if you want to use C<.html> files from
351 within a Catalyst app as static files, you need to change the
352 configuration of Static::Simple. Note also that files having any other
353 extension I<will> be served statically, so if you're using any other
354 extension for template files, you should also change the configuration.
356 Logging of static files is turned off by default.
358 =head1 ADVANCED CONFIGURATION
360 Configuration is completely optional and is specified within
361 C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}>. If you use any of these options,
362 this module will probably feel less "simple" to you!
364 =head2 Enabling request logging
366 Since Catalyst 5.50, logging of static requests is turned off by
367 default; static requests tend to clutter the log output and rarely
368 reveal anything useful. However, if you want to enable logging of static
369 requests, you can do so by setting
370 C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}-E<gt>{logging}> to 1.
372 =head2 Forcing directories into static mode
374 Define a list of top-level directories beneath your 'root' directory
375 that should always be served in static mode. Regular expressions may be
376 specified using C<qr//>.
379 'Plugin::Static::Simple' => {
387 =head2 Including additional directories
389 You may specify a list of directories in which to search for your static
390 files. The directories will be searched in order and will return the
391 first file found. Note that your root directory is B<not> automatically
392 added to the search path when you specify an C<include_path>. You should
393 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
396 'Plugin::Static::Simple' => {
400 MyApp->config->{root},
405 With the above setting, a request for the file C</images/logo.jpg> will search
406 for the following files, returning the first one found:
408 /path/to/overlay/images/logo.jpg
409 /dynamic/path/images/logo.jpg
410 /your/app/home/root/images/logo.jpg
412 The include path can contain a subroutine reference to dynamically return a
413 list of available directories. This method will receive the C<$c> object as a
414 parameter and should return a reference to a list of directories. Errors can
415 be reported using C<die()>. This method will be called every time a file is
416 requested that appears to be a static file (i.e. it has an extension).
420 sub incpath_generator {
423 if ( $c->session->{customer_dir} ) {
424 return [ $c->session->{customer_dir} ];
426 die "No customer dir defined.";
430 =head2 Ignoring certain types of files
432 There are some file types you may not wish to serve as static files.
433 Most important in this category are your raw template files. By
434 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
435 C<xhtml> will be ignored by Static::Simple in the interest of security.
436 If you wish to define your own extensions to ignore, use the
437 C<ignore_extensions> option:
440 'Plugin::Static::Simple' => {
441 ignore_extensions => [ qw/html asp php/ ],
445 =head2 Ignoring entire directories
447 To prevent an entire directory from being served statically, you can use
448 the C<ignore_dirs> option. This option contains a list of relative
449 directory paths to ignore. If using C<include_path>, the path will be
450 checked against every included path.
453 'Plugin::Static::Simple' => {
454 ignore_dirs => [ qw/tmpl css/ ],
458 For example, if combined with the above C<include_path> setting, this
459 C<ignore_dirs> value will ignore the following directories if they exist:
461 /path/to/overlay/tmpl
465 /your/app/home/root/tmpl
466 /your/app/home/root/css
468 =head2 Custom MIME types
470 To override or add to the default MIME types set by the L<MIME::Types>
471 module, you may enter your own extension to MIME type mapping.
474 'Plugin::Static::Simple' => {
482 =head2 Controlling caching with Expires header
484 The files served by Static::Simple will have a Last-Modified header set,
485 which allows some browsers to cache them for a while. However if you want
486 to explicitly set an Expires header, such as to allow proxies to cache your
487 static content, then you can do so by setting the "expires" config option.
489 The value indicates the number of seconds after access time to allow caching.
490 So a value of zero really means "don't cache at all", and any higher values
491 will keep the file around for that long.
494 'Plugin::Static::Simple' => {
495 expires => 3600, # Caching allowed for one hour.
499 =head2 Compatibility with other plugins
501 Since version 0.12, Static::Simple plays nice with other plugins. It no
502 longer short-circuits the C<prepare_action> stage as it was causing too
503 many compatibility issues with other plugins.
505 =head2 Debugging information
507 Enable additional debugging information printed in the Catalyst log. This
508 is automatically enabled when running Catalyst in -Debug mode.
511 'Plugin::Static::Simple' => {
516 =head1 USING WITH APACHE
518 While Static::Simple will work just fine serving files through Catalyst
519 in mod_perl, for increased performance you may wish to have Apache
520 handle the serving of your static files directly. To do this, simply use
521 a dedicated directory for your static files and configure an Apache
522 Location block for that directory This approach is recommended for
523 production installations.
525 <Location /myapp/static>
526 SetHandler default-handler
529 Using this approach Apache will bypass any handling of these directories
530 through Catalyst. You can leave Static::Simple as part of your
531 application, and it will continue to function on a development server,
532 or using Catalyst's built-in server.
534 In practice, your Catalyst application is probably (i.e. should be)
535 structured in the recommended way (i.e., that generated by bootstrapping
536 the application with the C<catalyst.pl> script, with a main directory
537 under which is a C<lib/> directory for module files and a C<root/>
538 directory for templates and static files). Thus, unless you break up
539 this structure when deploying your app by moving the static files to a
540 different location in your filesystem, you will need to use an Alias
541 directive in Apache to point to the right place. You will then need to
542 add a Directory block to give permission for Apache to serve these
543 files. The final configuration will look something like this:
545 Alias /myapp/static /filesystem/path/to/MyApp/root/static
546 <Directory /filesystem/path/to/MyApp/root/static>
549 <Location /myapp/static>
550 SetHandler default-handler
553 If you are running in a VirtualHost, you can just set the DocumentRoot
554 location to the location of your root directory; see
555 L<Catalyst::Engine::Apache2::MP20>.
557 =head1 PUBLIC METHODS
559 =head2 serve_static_file $file_path
561 Will serve the file located in $file_path statically. This is useful when
562 you need to autogenerate them if they don't exist, or they are stored in a model.
564 package MyApp::Controller::User;
566 sub curr_user_thumb : PathPart("my_thumbnail.png") {
567 my ( $self, $c ) = @_;
568 my $file_path = $c->user->picture_thumbnail_path;
569 $c->serve_static_file($file_path);
572 =head1 INTERNAL EXTENDED METHODS
574 Static::Simple extends the following steps in the Catalyst process.
576 =head2 prepare_action
578 C<prepare_action> is used to first check if the request path is a static
579 file. If so, we skip all other C<prepare_action> steps to improve
584 C<dispatch> takes the file found during C<prepare_action> and writes it
589 C<finalize> serves up final header information and displays any log
594 C<setup> initializes all default values.
598 The old style of configuration using the C<'static'> config key was deprecated
599 in version 0.30. A warning will be issued if this is used, and the contents of
600 the config at this key will be merged with the newer C<'Plugin::Static::Simple'>
603 Be aware that if the C<'include_path'> key under C<'static'> exists at all, it
604 will be merged with any content of the same key under
605 C<'Plugin::Static::Simple'>. Be careful not to set this to a non-arrayref,
610 L<Catalyst>, L<Catalyst::Plugin::Static>,
611 L<http://www.iana.org/assignments/media-types/>
615 Andy Grundman, <andy@hybridized.org>
619 Marcus Ramberg, <mramberg@cpan.org>
621 Jesse Sheidlower, <jester@panix.com>
623 Guillermo Roditi, <groditi@cpan.org>
625 Florian Ragwitz, <rafl@debian.org>
627 Tomas Doran, <bobtfish@bobtfish.net>
631 Matt S Trout, <mst@shadowcat.co.uk>
633 Toby Corkindale, <tjc@wintrmute.net>
637 The authors of Catalyst::Plugin::Static:
643 For the include_path code from Template Toolkit:
649 Copyright (c) 2005 - 2011
650 the Catalyst::Plugin::Static::Simple L</AUTHOR> and L</CONTRIBUTORS>
655 This program is free software, you can redistribute it and/or modify it under
656 the same terms as Perl itself.