1 package Catalyst::Plugin::Static::Simple;
8 use MooseX::Types::Moose qw/ArrayRef Str/;
10 use namespace::autoclean;
12 our $VERSION = '0.35';
14 has _static_file => ( is => 'rw' );
15 has _static_debug_message => ( is => 'rw', isa => ArrayRef[Str] );
17 after setup_finalize => sub {
20 # New: Turn off new 'autoflush' flag in logger (see Catalyst::Log).
21 # This is needed to surpress output of debug log messages for
23 $c->log->autoflush(0) if $c->log->can('autoflush');
26 before prepare_action => sub {
28 my $path = $c->req->path;
29 my $config = $c->config->{'Plugin::Static::Simple'};
31 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
33 # is the URI in a static-defined path?
34 foreach my $dir ( @{ $config->{dirs} } ) {
35 my $dir_re = quotemeta $dir;
37 # strip trailing slashes, they'll be added in our regex
42 if ( $dir =~ m{^qr/}xms ) {
46 $c->error( "Error compiling static dir regex '$dir': $@" );
50 $re = qr{^${dir_re}/};
54 if ( $c->_locate_static_file( $path, 1 ) ) {
55 $c->_debug_msg( 'from static directory' )
58 $c->_debug_msg( "404: file not found: $path" )
60 $c->res->status( 404 );
61 $c->res->content_type( 'text/html' );
66 # Does the path have an extension?
67 if ( $path =~ /\.([^\/\\]+)$/m ) {
69 $c->_locate_static_file( $path );
73 around dispatch => sub {
77 return if ( $c->res->status != 200 );
79 if ( $c->_static_file ) {
80 if ( $c->config->{'Plugin::Static::Simple'}->{no_logs} && $c->log->can('abort') ) {
83 return $c->_serve_static;
90 before finalize => sub {
93 # display all log messages
94 if ( $c->config->{'Plugin::Static::Simple'}->{debug} && scalar @{$c->_debug_msg} ) {
95 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
99 before setup_finalize => sub {
102 $c->log->warn("Deprecated 'static' config key used, please use the key 'Plugin::Static::Simple' instead")
103 if exists $c->config->{static};
105 if (exists $c->config->{static}->{include_path}) {
106 $c->config->{'Plugin::Static::Simple'}->{include_path} = [
107 @{$c->config->{'Plugin::Static::Simple'}->{include_path} || []},
108 @{delete $c->config->{static}->{include_path} || []}
113 = $c->config->{'Plugin::Static::Simple'}
114 = $c->config->{'static'}
115 = Catalyst::Utils::merge_hashes(
116 $c->config->{'Plugin::Static::Simple'} || {},
117 $c->config->{static} || {}
120 $config->{dirs} ||= [];
121 $config->{include_path} ||= [ $c->config->{root} ];
122 $config->{mime_types} ||= {};
123 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
124 $config->{ignore_dirs} ||= [];
125 $config->{debug} ||= $c->debug;
126 $config->{no_logs} = 1 unless defined $config->{no_logs};
127 $config->{no_logs} = 0 if $config->{logging};
129 # load up a MIME::Types object, only loading types with
130 # at least 1 file extension
131 $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
134 # Search through all included directories for the static file
135 # Based on Template Toolkit INCLUDE_PATH code
136 sub _locate_static_file {
137 my ( $c, $path, $in_static_dir ) = @_;
139 $path = File::Spec->catdir(
140 File::Spec->no_upwards( File::Spec->splitdir( $path ) )
143 my $config = $c->config->{'Plugin::Static::Simple'};
144 my @ipaths = @{ $config->{include_path} };
146 my $count = 64; # maximum number of directories to search
149 while ( @ipaths && --$count) {
150 my $dir = shift @ipaths || next DIR_CHECK;
152 if ( ref $dir eq 'CODE' ) {
153 eval { $dpaths = &$dir( $c ) };
155 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
157 unshift @ipaths, @$dpaths;
161 $dir =~ s/(\/|\\)$//xms;
162 if ( -d $dir && -f $dir . '/' . $path ) {
164 # Don't ignore any files in static dirs defined with 'dirs'
165 unless ( $in_static_dir ) {
166 # do we need to ignore the file?
167 for my $ignore ( @{ $config->{ignore_dirs} } ) {
168 $ignore =~ s{(/|\\)$}{};
169 if ( $path =~ /^$ignore(\/|\\)/ ) {
170 $c->_debug_msg( "Ignoring directory `$ignore`" )
176 # do we need to ignore based on extension?
177 for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
178 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
179 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
186 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
188 return $c->_static_file( $dir . '/' . $path );
198 my $config = $c->config->{'Plugin::Static::Simple'};
200 my $full_path = shift || $c->_static_file;
201 my $type = $c->_ext_to_type( $full_path );
202 my $stat = stat $full_path;
204 $c->res->headers->content_type( $type );
205 $c->res->headers->content_length( $stat->size );
206 $c->res->headers->last_modified( $stat->mtime );
207 # Tell Firefox & friends its OK to cache, even over SSL:
208 $c->res->headers->header('Cache-control' => 'public');
209 # Optionally, set a fixed expiry time:
210 if ($config->{expires}) {
211 $c->res->headers->expires(time() + $config->{expires});
214 my $fh = IO::File->new( $full_path, 'r' );
217 $c->res->body( $fh );
220 Catalyst::Exception->throw(
221 message => "Unable to open $full_path for reading" );
227 sub serve_static_file {
228 my ( $c, $full_path ) = @_;
230 my $config = $c->config->{'Plugin::Static::Simple'};
232 if ( -e $full_path ) {
233 $c->_debug_msg( "Serving static file: $full_path" )
237 $c->_debug_msg( "404: file not found: $full_path" )
239 $c->res->status( 404 );
240 $c->res->content_type( 'text/html' );
244 $c->_serve_static( $full_path );
247 # looks up the correct MIME type for the current file extension
249 my ( $c, $full_path ) = @_;
251 my $config = $c->config->{'Plugin::Static::Simple'};
253 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
255 my $type = $config->{mime_types}{$ext}
256 || $config->{mime_types_obj}->mimeTypeOf( $ext );
258 $c->_debug_msg( "as $type" ) if $config->{debug};
259 return ( ref $type ) ? $type->type : $type;
262 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
268 $c->_debug_msg( 'as text/plain (no extension)' )
275 my ( $c, $msg ) = @_;
277 if ( !defined $c->_static_debug_message ) {
278 $c->_static_debug_message( [] );
282 push @{ $c->_static_debug_message }, $msg;
285 return $c->_static_debug_message;
293 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
298 use Catalyst qw/ Static::Simple /;
300 # that's it; static content is automatically served by Catalyst
301 # from the application's root directory, though you can configure
302 # things or bypass Catalyst entirely in a production environment
304 # one caveat: the files must be served from an absolute path
305 # (i.e. /images/foo.png)
309 The Static::Simple plugin is designed to make serving static content in
310 your application during development quick and easy, without requiring a
311 single line of code from you.
313 This plugin detects static files by looking at the file extension in the
314 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
315 lightweight L<MIME::Types> module to map file extensions to
316 IANA-registered MIME types, and will serve your static files with the
317 correct MIME type directly to the browser, without being processed
320 Note that actions mapped to paths using periods (.) will still operate
323 If the plugin can not find the file, the request is dispatched to your
324 application instead. This means you are responsible for generating a
325 C<404> error if your application can not process the request:
327 # handled by static::simple, not dispatched to your application
330 # static::simple will not find the file and let your application
331 # handle the request. You are responsible for generating a file
332 # or returning a 404 error
333 /images/does_not_exist.png
335 Though Static::Simple is designed to work out-of-the-box, you can tweak
336 the operation by adding various configuration options. In a production
337 environment, you will probably want to use your webserver to deliver
338 static content; for an example see L<USING WITH APACHE>, below.
340 =head1 DEFAULT BEHAVIOUR
342 By default, Static::Simple will deliver all files having extensions
343 (that is, bits of text following a period (C<.>)), I<except> files
344 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
345 C<xhtml>. These files, and all files without extensions, will be
346 processed through Catalyst. If L<MIME::Types> doesn't recognize an
347 extension, it will be served as C<text/plain>.
349 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
350 and C<xhtml> I<will not> be served statically by default, they will be
351 processed by Catalyst. Thus if you want to use C<.html> files from
352 within a Catalyst app as static files, you need to change the
353 configuration of Static::Simple. Note also that files having any other
354 extension I<will> be served statically, so if you're using any other
355 extension for template files, you should also change the configuration.
357 Logging of static files is turned off by default.
359 =head1 ADVANCED CONFIGURATION
361 Configuration is completely optional and is specified within
362 C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}>. If you use any of these options,
363 this module will probably feel less "simple" to you!
365 =head2 Enabling request logging
367 Since Catalyst 5.50, logging of static requests is turned off by
368 default; static requests tend to clutter the log output and rarely
369 reveal anything useful. However, if you want to enable logging of static
370 requests, you can do so by setting
371 C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}-E<gt>{logging}> to 1.
373 =head2 Forcing directories into static mode
375 Define a list of top-level directories beneath your 'root' directory
376 that should always be served in static mode. Regular expressions may be
377 specified using C<qr//>.
380 'Plugin::Static::Simple' => {
388 =head2 Including additional directories
390 You may specify a list of directories in which to search for your static
391 files. The directories will be searched in order and will return the
392 first file found. Note that your root directory is B<not> automatically
393 added to the search path when you specify an C<include_path>. You should
394 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
397 'Plugin::Static::Simple' => {
401 MyApp->config->{root},
406 With the above setting, a request for the file C</images/logo.jpg> will search
407 for the following files, returning the first one found:
409 /path/to/overlay/images/logo.jpg
410 /dynamic/path/images/logo.jpg
411 /your/app/home/root/images/logo.jpg
413 The include path can contain a subroutine reference to dynamically return a
414 list of available directories. This method will receive the C<$c> object as a
415 parameter and should return a reference to a list of directories. Errors can
416 be reported using C<die()>. This method will be called every time a file is
417 requested that appears to be a static file (i.e. it has an extension).
421 sub incpath_generator {
424 if ( $c->session->{customer_dir} ) {
425 return [ $c->session->{customer_dir} ];
427 die "No customer dir defined.";
431 =head2 Ignoring certain types of files
433 There are some file types you may not wish to serve as static files.
434 Most important in this category are your raw template files. By
435 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
436 C<xhtml> will be ignored by Static::Simple in the interest of security.
437 If you wish to define your own extensions to ignore, use the
438 C<ignore_extensions> option:
441 'Plugin::Static::Simple' => {
442 ignore_extensions => [ qw/html asp php/ ],
446 =head2 Ignoring entire directories
448 To prevent an entire directory from being served statically, you can use
449 the C<ignore_dirs> option. This option contains a list of relative
450 directory paths to ignore. If using C<include_path>, the path will be
451 checked against every included path.
454 'Plugin::Static::Simple' => {
455 ignore_dirs => [ qw/tmpl css/ ],
459 For example, if combined with the above C<include_path> setting, this
460 C<ignore_dirs> value will ignore the following directories if they exist:
462 /path/to/overlay/tmpl
466 /your/app/home/root/tmpl
467 /your/app/home/root/css
469 =head2 Custom MIME types
471 To override or add to the default MIME types set by the L<MIME::Types>
472 module, you may enter your own extension to MIME type mapping.
475 'Plugin::Static::Simple' => {
483 =head2 Controlling caching with Expires header
485 The files served by Static::Simple will have a Last-Modified header set,
486 which allows some browsers to cache them for a while. However if you want
487 to explicitly set an Expires header, such as to allow proxies to cache your
488 static content, then you can do so by setting the "expires" config option.
490 The value indicates the number of seconds after access time to allow caching.
491 So a value of zero really means "don't cache at all", and any higher values
492 will keep the file around for that long.
495 'Plugin::Static::Simple' => {
496 expires => 3600, # Caching allowed for one hour.
500 =head2 Compatibility with other plugins
502 Since version 0.12, Static::Simple plays nice with other plugins. It no
503 longer short-circuits the C<prepare_action> stage as it was causing too
504 many compatibility issues with other plugins.
506 =head2 Debugging information
508 Enable additional debugging information printed in the Catalyst log. This
509 is automatically enabled when running Catalyst in -Debug mode.
512 'Plugin::Static::Simple' => {
517 =head1 USING WITH APACHE
519 While Static::Simple will work just fine serving files through Catalyst
520 in mod_perl, for increased performance you may wish to have Apache
521 handle the serving of your static files directly. To do this, simply use
522 a dedicated directory for your static files and configure an Apache
523 Location block for that directory This approach is recommended for
524 production installations.
526 <Location /myapp/static>
527 SetHandler default-handler
530 Using this approach Apache will bypass any handling of these directories
531 through Catalyst. You can leave Static::Simple as part of your
532 application, and it will continue to function on a development server,
533 or using Catalyst's built-in server.
535 In practice, your Catalyst application is probably (i.e. should be)
536 structured in the recommended way (i.e., that generated by bootstrapping
537 the application with the C<catalyst.pl> script, with a main directory
538 under which is a C<lib/> directory for module files and a C<root/>
539 directory for templates and static files). Thus, unless you break up
540 this structure when deploying your app by moving the static files to a
541 different location in your filesystem, you will need to use an Alias
542 directive in Apache to point to the right place. You will then need to
543 add a Directory block to give permission for Apache to serve these
544 files. The final configuration will look something like this:
546 Alias /myapp/static /filesystem/path/to/MyApp/root/static
547 <Directory /filesystem/path/to/MyApp/root/static>
550 <Location /myapp/static>
551 SetHandler default-handler
554 If you are running in a VirtualHost, you can just set the DocumentRoot
555 location to the location of your root directory; see
556 L<Catalyst::Engine::Apache2::MP20>.
558 =head1 PUBLIC METHODS
560 =head2 serve_static_file $file_path
562 Will serve the file located in $file_path statically. This is useful when
563 you need to autogenerate them if they don't exist, or they are stored in a model.
565 package MyApp::Controller::User;
567 sub curr_user_thumb : PathPart("my_thumbnail.png") {
568 my ( $self, $c ) = @_;
569 my $file_path = $c->user->picture_thumbnail_path;
570 $c->serve_static_file($file_path);
573 =head1 INTERNAL EXTENDED METHODS
575 Static::Simple extends the following steps in the Catalyst process.
577 =head2 prepare_action
579 C<prepare_action> is used to first check if the request path is a static
580 file. If so, we skip all other C<prepare_action> steps to improve
585 C<dispatch> takes the file found during C<prepare_action> and writes it
590 C<finalize> serves up final header information and displays any log
595 C<setup> initializes all default values.
599 The old style of configuration using the C<'static'> config key was deprecated
600 in version 0.30. A warning will be issued if this is used, and the contents of
601 the config at this key will be merged with the newer C<'Plugin::Static::Simple'>
604 Be aware that if the C<'include_path'> key under C<'static'> exists at all, it
605 will be merged with any content of the same key under
606 C<'Plugin::Static::Simple'>. Be careful not to set this to a non-arrayref,
611 L<Catalyst>, L<Catalyst::Plugin::Static>,
612 L<http://www.iana.org/assignments/media-types/>
616 Andy Grundman, <andy@hybridized.org>
620 Marcus Ramberg, <mramberg@cpan.org>
622 Jesse Sheidlower, <jester@panix.com>
624 Guillermo Roditi, <groditi@cpan.org>
626 Florian Ragwitz, <rafl@debian.org>
628 Tomas Doran, <bobtfish@bobtfish.net>
632 Matt S Trout, <mst@shadowcat.co.uk>
634 Toby Corkindale, <tjc@wintrmute.net>
638 The authors of Catalyst::Plugin::Static:
644 For the include_path code from Template Toolkit:
650 Copyright (c) 2005 - 2011
651 the Catalyst::Plugin::Static::Simple L</AUTHOR> and L</CONTRIBUTORS>
656 This program is free software, you can redistribute it and/or modify it under
657 the same terms as Perl itself.