1 package Catalyst::Plugin::Static::Simple;
5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
12 our $VERSION = '0.21';
14 __PACKAGE__->mk_accessors( qw/_static_file _static_debug_message/ );
16 my $CONFIG_KEY = "Plugin::Static::Simple";
20 my $path = $c->req->path;
21 my $config = $c->config->{$CONFIG_KEY} ||= $c->config->{static};
23 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
25 # is the URI in a static-defined path?
26 foreach my $dir ( @{ $config->{dirs} } ) {
27 my $dir_re = quotemeta $dir;
29 # strip trailing slashes, they'll be added in our regex
32 my $re = ( $dir =~ m{^qr/}xms ) ? eval $dir : qr{^${dir_re}/};
34 $c->error( "Error compiling static dir regex '$dir': $@" );
37 if ( $c->_locate_static_file( $path, 1 ) ) {
38 $c->_debug_msg( 'from static directory' )
41 $c->_debug_msg( "404: file not found: $path" )
43 $c->res->status( 404 );
44 $c->res->content_type( 'text/html' );
49 # Does the path have an extension?
50 if ( $path =~ /.*\.(\S{1,})$/xms ) {
52 $c->_locate_static_file( $path );
55 return $c->next::method(@_);
61 return if ( $c->res->status != 200 );
63 if ( $c->_static_file ) {
64 if ( $c->config->{$CONFIG_KEY}{no_logs} && $c->log->can('abort') ) {
67 return $c->_serve_static;
70 return $c->next::method(@_);
77 # display all log messages
78 if ( $c->config->{$CONFIG_KEY}{debug} && scalar @{$c->_debug_msg} ) {
79 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
82 return $c->next::method(@_);
88 $c->maybe::next::method(@_);
90 if ( Catalyst->VERSION le '5.33' ) {
94 my $config = $c->config->{$CONFIG_KEY} ||= {};
96 $config->{dirs} ||= [];
97 $config->{include_path} ||= [ $c->config->{root} ];
98 $config->{mime_types} ||= {};
99 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
100 $config->{ignore_dirs} ||= [];
101 $config->{debug} ||= $c->debug;
102 $config->{no_logs} = 1 unless defined $config->{no_logs};
103 $config->{no_logs} = 0 if $config->{logging};
105 # load up a MIME::Types object, only loading types with
106 # at least 1 file extension
107 $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
109 # preload the type index hash so it's not built on the first request
110 $config->{mime_types_obj}->create_type_index;
113 # Search through all included directories for the static file
114 # Based on Template Toolkit INCLUDE_PATH code
115 sub _locate_static_file {
116 my ( $c, $path, $in_static_dir ) = @_;
118 $path = File::Spec->catdir(
119 File::Spec->no_upwards( File::Spec->splitdir( $path ) )
122 my $config = $c->config->{$CONFIG_KEY};
123 my @ipaths = @{ $config->{include_path} };
125 my $count = 64; # maximum number of directories to search
128 while ( @ipaths && --$count) {
129 my $dir = shift @ipaths || next DIR_CHECK;
131 if ( ref $dir eq 'CODE' ) {
132 eval { $dpaths = &$dir( $c ) };
134 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
136 unshift @ipaths, @$dpaths;
140 $dir =~ s/(\/|\\)$//xms;
141 if ( -d $dir && -f $dir . '/' . $path ) {
143 # Don't ignore any files in static dirs defined with 'dirs'
144 unless ( $in_static_dir ) {
145 # do we need to ignore the file?
146 for my $ignore ( @{ $config->{ignore_dirs} } ) {
147 $ignore =~ s{(/|\\)$}{};
148 if ( $path =~ /^$ignore(\/|\\)/ ) {
149 $c->_debug_msg( "Ignoring directory `$ignore`" )
155 # do we need to ignore based on extension?
156 for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
157 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
158 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
165 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
167 return $c->_static_file( $dir . '/' . $path );
178 my $full_path = shift || $c->_static_file;
179 my $type = $c->_ext_to_type( $full_path );
180 my $stat = stat $full_path;
182 $c->res->headers->content_type( $type );
183 $c->res->headers->content_length( $stat->size );
184 $c->res->headers->last_modified( $stat->mtime );
186 if ( Catalyst->VERSION le '5.33' ) {
187 # old File::Slurp method
188 my $content = File::Slurp::read_file( $full_path );
189 $c->res->body( $content );
192 # new method, pass an IO::File object to body
193 my $fh = IO::File->new( $full_path, 'r' );
196 $c->res->body( $fh );
199 Catalyst::Exception->throw(
200 message => "Unable to open $full_path for reading" );
207 sub serve_static_file {
208 my ( $c, $full_path ) = @_;
210 my $config = $c->config->{$CONFIG_KEY} ||= {};
212 if ( -e $full_path ) {
213 $c->_debug_msg( "Serving static file: $full_path" )
217 $c->_debug_msg( "404: file not found: $full_path" )
219 $c->res->status( 404 );
220 $c->res->content_type( 'text/html' );
224 $c->_serve_static( $full_path );
227 # looks up the correct MIME type for the current file extension
229 my ( $c, $full_path ) = @_;
231 my $config = $c->config->{$CONFIG_KEY};
233 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
235 my $type = $config->{mime_types}{$ext}
236 || $config->{mime_types_obj}->mimeTypeOf( $ext );
238 $c->_debug_msg( "as $type" ) if $config->{debug};
239 return ( ref $type ) ? $type->type : $type;
242 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
248 $c->_debug_msg( 'as text/plain (no extension)' )
255 my ( $c, $msg ) = @_;
257 if ( !defined $c->_static_debug_message ) {
258 $c->_static_debug_message( [] );
262 push @{ $c->_static_debug_message }, $msg;
265 return $c->_static_debug_message;
273 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
278 use Catalyst qw/ Static::Simple /;
280 # that's it; static content is automatically served by Catalyst
281 # from the application's root directory, though you can configure
282 # things or bypass Catalyst entirely in a production environment
284 # one caveat: the files must be served from an absolute path
285 # (i.e. /images/foo.png)
289 The Static::Simple plugin is designed to make serving static content in
290 your application during development quick and easy, without requiring a
291 single line of code from you.
293 This plugin detects static files by looking at the file extension in the
294 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
295 lightweight L<MIME::Types> module to map file extensions to
296 IANA-registered MIME types, and will serve your static files with the
297 correct MIME type directly to the browser, without being processed
300 Note that actions mapped to paths using periods (.) will still operate
303 If the plugin can not find the file, the request is dispatched to your
304 application instead. This means you are responsible for generating a
305 C<404> error if your applicaton can not process the request:
307 # handled by static::simple, not dispatched to your application
310 # static::simple will not find the file and let your application
311 # handle the request. You are responsible for generating a file
312 # or returning a 404 error
313 /images/does_not_exist.png
315 Though Static::Simple is designed to work out-of-the-box, you can tweak
316 the operation by adding various configuration options. In a production
317 environment, you will probably want to use your webserver to deliver
318 static content; for an example see L<USING WITH APACHE>, below.
320 =head1 DEFAULT BEHAVIOR
322 By default, Static::Simple will deliver all files having extensions
323 (that is, bits of text following a period (C<.>)), I<except> files
324 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
325 C<xhtml>. These files, and all files without extensions, will be
326 processed through Catalyst. If L<MIME::Types> doesn't recognize an
327 extension, it will be served as C<text/plain>.
329 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
330 and C<xhtml> I<will not> be served statically by default, they will be
331 processed by Catalyst. Thus if you want to use C<.html> files from
332 within a Catalyst app as static files, you need to change the
333 configuration of Static::Simple. Note also that files having any other
334 extension I<will> be served statically, so if you're using any other
335 extension for template files, you should also change the configuration.
337 Logging of static files is turned off by default.
339 =head1 ADVANCED CONFIGURATION
341 Configuration is completely optional and is specified within
342 C<MyApp-E<gt>config-E<gt>{'Plugin::Static::Simple'}>. If you use any of these
343 options, this module will probably feel less "simple" to you!
345 =head2 Enabling request logging
347 Since Catalyst 5.50, logging of static requests is turned off by
348 default; static requests tend to clutter the log output and rarely
349 reveal anything useful. However, if you want to enable logging of static
350 requests, you can do so by setting
351 C<MyApp-E<gt>config-E<gt>{'Plugin::Static::Simple'}-E<gt>{logging}> to 1.
353 =head2 Forcing directories into static mode
355 Define a list of top-level directories beneath your 'root' directory
356 that should always be served in static mode. Regular expressions may be
357 specified using C<qr//>.
359 MyApp->config->{'Plugin::Static::Simple'}->{dirs} = [
364 =head2 Including additional directories
366 You may specify a list of directories in which to search for your static
367 files. The directories will be searched in order and will return the
368 first file found. Note that your root directory is B<not> automatically
369 added to the search path when you specify an C<include_path>. You should
370 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
372 MyApp->config->{'Plugin::Static::Simple'}->{include_path} = [
375 MyApp->config->{root}
378 With the above setting, a request for the file C</images/logo.jpg> will search
379 for the following files, returning the first one found:
381 /path/to/overlay/images/logo.jpg
382 /dynamic/path/images/logo.jpg
383 /your/app/home/root/images/logo.jpg
385 The include path can contain a subroutine reference to dynamically return a
386 list of available directories. This method will receive the C<$c> object as a
387 parameter and should return a reference to a list of directories. Errors can
388 be reported using C<die()>. This method will be called every time a file is
389 requested that appears to be a static file (i.e. it has an extension).
393 sub incpath_generator {
396 if ( $c->session->{customer_dir} ) {
397 return [ $c->session->{customer_dir} ];
399 die "No customer dir defined.";
403 =head2 Ignoring certain types of files
405 There are some file types you may not wish to serve as static files.
406 Most important in this category are your raw template files. By
407 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
408 C<xhtml> will be ignored by Static::Simple in the interest of security.
409 If you wish to define your own extensions to ignore, use the
410 C<ignore_extensions> option:
412 MyApp->config->{'Plugin::Static::Simple'}->{ignore_extensions}
413 = [ qw/html asp php/ ];
415 =head2 Ignoring entire directories
417 To prevent an entire directory from being served statically, you can use
418 the C<ignore_dirs> option. This option contains a list of relative
419 directory paths to ignore. If using C<include_path>, the path will be
420 checked against every included path.
422 MyApp->config->{'Plugin::Static::Simple'}->{ignore_dirs} = [ qw/tmpl css/ ];
424 For example, if combined with the above C<include_path> setting, this
425 C<ignore_dirs> value will ignore the following directories if they exist:
427 /path/to/overlay/tmpl
431 /your/app/home/root/tmpl
432 /your/app/home/root/css
434 =head2 Custom MIME types
436 To override or add to the default MIME types set by the L<MIME::Types>
437 module, you may enter your own extension to MIME type mapping.
439 MyApp->config->{'Plugin::Static::Simple'}->{mime_types} = {
444 =head2 Compatibility with other plugins
446 Since version 0.12, Static::Simple plays nice with other plugins. It no
447 longer short-circuits the C<prepare_action> stage as it was causing too
448 many compatibility issues with other plugins.
450 =head2 Debugging information
452 Enable additional debugging information printed in the Catalyst log. This
453 is automatically enabled when running Catalyst in -Debug mode.
455 MyApp->config->{'Plugin::Static::Simple'}->{debug} = 1;
457 =head1 USING WITH APACHE
459 While Static::Simple will work just fine serving files through Catalyst
460 in mod_perl, for increased performance you may wish to have Apache
461 handle the serving of your static files directly. To do this, simply use
462 a dedicated directory for your static files and configure an Apache
463 Location block for that directory This approach is recommended for
464 production installations.
466 <Location /myapp/static>
467 SetHandler default-handler
470 Using this approach Apache will bypass any handling of these directories
471 through Catalyst. You can leave Static::Simple as part of your
472 application, and it will continue to function on a development server,
473 or using Catalyst's built-in server.
475 In practice, your Catalyst application is probably (i.e. should be)
476 structured in the recommended way (i.e., that generated by bootstrapping
477 the application with the C<catalyst.pl> script, with a main directory
478 under which is a C<lib/> directory for module files and a C<root/>
479 directory for templates and static files). Thus, unless you break up
480 this structure when deploying your app by moving the static files to a
481 different location in your filesystem, you will need to use an Alias
482 directive in Apache to point to the right place. You will then need to
483 add a Directory block to give permission for Apache to serve these
484 files. The final configuration will look something like this:
486 Alias /myapp/static /filesystem/path/to/MyApp/root/static
487 <Directory /filesystem/path/to/MyApp/root/static>
490 <Location /myapp/static>
491 SetHandler default-handler
494 If you are running in a VirtualHost, you can just set the DocumentRoot
495 location to the location of your root directory; see
496 L<Catalyst::Engine::Apache2::MP20>.
498 =head1 PUBLIC METHODS
500 =head2 serve_static_file $file_path
502 Will serve the file located in $file_path statically. This is useful when
503 you need to autogenerate them if they don't exist, or they are stored in a model.
505 package MyApp::Controller::User;
507 sub curr_user_thumb : PathPart("my_thumbnail.png") {
508 my ( $self, $c ) = @_;
509 my $file_path = $c->user->picture_thumbnail_path;
510 $c->serve_static_file($file_path);
513 =head1 INTERNAL EXTENDED METHODS
515 Static::Simple extends the following steps in the Catalyst process.
517 =head2 prepare_action
519 C<prepare_action> is used to first check if the request path is a static
520 file. If so, we skip all other C<prepare_action> steps to improve
525 C<dispatch> takes the file found during C<prepare_action> and writes it
530 C<finalize> serves up final header information and displays any log
535 C<setup> initializes all default values.
539 L<Catalyst>, L<Catalyst::Plugin::Static>,
540 L<http://www.iana.org/assignments/media-types/>
544 Andy Grundman, <andy@hybridized.org>
548 Marcus Ramberg, <mramberg@cpan.org>
550 Jesse Sheidlower, <jester@panix.com>
552 Guillermo Roditi, <groditi@cpan.org>
556 The authors of Catalyst::Plugin::Static:
562 For the include_path code from Template Toolkit:
568 This program is free software, you can redistribute it and/or modify it under
569 the same terms as Perl itself.