1 package Catalyst::Plugin::Static::Simple;
5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
12 our $VERSION = '0.26';
14 __PACKAGE__->mk_accessors( qw/_static_file _static_debug_message/ );
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 );
62 return $c->next::method(@_);
68 return if ( $c->res->status != 200 );
70 if ( $c->_static_file ) {
71 if ( $c->config->{static}{no_logs} && $c->log->can('abort') ) {
74 return $c->_serve_static;
77 return $c->next::method(@_);
84 # display all log messages
85 if ( $c->config->{static}{debug} && scalar @{$c->_debug_msg} ) {
86 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
89 return $c->next::method(@_);
95 $c->maybe::next::method(@_);
97 my $config = $c->config->{static} ||= {};
99 $config->{dirs} ||= [];
100 $config->{include_path} ||= [ $c->config->{root} ];
101 $config->{mime_types} ||= {};
102 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
103 $config->{ignore_dirs} ||= [];
104 $config->{debug} ||= $c->debug;
105 $config->{no_logs} = 1 unless defined $config->{no_logs};
106 $config->{no_logs} = 0 if $config->{logging};
108 # load up a MIME::Types object, only loading types with
109 # at least 1 file extension
110 $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
112 # preload the type index hash so it's not built on the first request
113 $config->{mime_types_obj}->create_type_index;
116 # Search through all included directories for the static file
117 # Based on Template Toolkit INCLUDE_PATH code
118 sub _locate_static_file {
119 my ( $c, $path, $in_static_dir ) = @_;
121 $path = File::Spec->catdir(
122 File::Spec->no_upwards( File::Spec->splitdir( $path ) )
125 my $config = $c->config->{static};
126 my @ipaths = @{ $config->{include_path} };
128 my $count = 64; # maximum number of directories to search
131 while ( @ipaths && --$count) {
132 my $dir = shift @ipaths || next DIR_CHECK;
134 if ( ref $dir eq 'CODE' ) {
135 eval { $dpaths = &$dir( $c ) };
137 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
139 unshift @ipaths, @$dpaths;
143 $dir =~ s/(\/|\\)$//xms;
144 if ( -d $dir && -f $dir . '/' . $path ) {
146 # Don't ignore any files in static dirs defined with 'dirs'
147 unless ( $in_static_dir ) {
148 # do we need to ignore the file?
149 for my $ignore ( @{ $config->{ignore_dirs} } ) {
150 $ignore =~ s{(/|\\)$}{};
151 if ( $path =~ /^$ignore(\/|\\)/ ) {
152 $c->_debug_msg( "Ignoring directory `$ignore`" )
158 # do we need to ignore based on extension?
159 for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
160 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
161 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
168 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
170 return $c->_static_file( $dir . '/' . $path );
181 my $full_path = shift || $c->_static_file;
182 my $type = $c->_ext_to_type( $full_path );
183 my $stat = stat $full_path;
185 $c->res->headers->content_type( $type );
186 $c->res->headers->content_length( $stat->size );
187 $c->res->headers->last_modified( $stat->mtime );
189 my $fh = IO::File->new( $full_path, 'r' );
192 $c->res->body( $fh );
195 Catalyst::Exception->throw(
196 message => "Unable to open $full_path for reading" );
202 sub serve_static_file {
203 my ( $c, $full_path ) = @_;
205 my $config = $c->config->{static} ||= {};
207 if ( -e $full_path ) {
208 $c->_debug_msg( "Serving static file: $full_path" )
212 $c->_debug_msg( "404: file not found: $full_path" )
214 $c->res->status( 404 );
215 $c->res->content_type( 'text/html' );
219 $c->_serve_static( $full_path );
222 # looks up the correct MIME type for the current file extension
224 my ( $c, $full_path ) = @_;
226 my $config = $c->config->{static};
228 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
230 my $type = $config->{mime_types}{$ext}
231 || $config->{mime_types_obj}->mimeTypeOf( $ext );
233 $c->_debug_msg( "as $type" ) if $config->{debug};
234 return ( ref $type ) ? $type->type : $type;
237 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
243 $c->_debug_msg( 'as text/plain (no extension)' )
250 my ( $c, $msg ) = @_;
252 if ( !defined $c->_static_debug_message ) {
253 $c->_static_debug_message( [] );
257 push @{ $c->_static_debug_message }, $msg;
260 return $c->_static_debug_message;
268 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
273 use Catalyst qw/ Static::Simple /;
275 # that's it; static content is automatically served by Catalyst
276 # from the application's root directory, though you can configure
277 # things or bypass Catalyst entirely in a production environment
279 # one caveat: the files must be served from an absolute path
280 # (i.e. /images/foo.png)
284 The Static::Simple plugin is designed to make serving static content in
285 your application during development quick and easy, without requiring a
286 single line of code from you.
288 This plugin detects static files by looking at the file extension in the
289 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
290 lightweight L<MIME::Types> module to map file extensions to
291 IANA-registered MIME types, and will serve your static files with the
292 correct MIME type directly to the browser, without being processed
295 Note that actions mapped to paths using periods (.) will still operate
298 If the plugin can not find the file, the request is dispatched to your
299 application instead. This means you are responsible for generating a
300 C<404> error if your applicaton can not process the request:
302 # handled by static::simple, not dispatched to your application
305 # static::simple will not find the file and let your application
306 # handle the request. You are responsible for generating a file
307 # or returning a 404 error
308 /images/does_not_exist.png
310 Though Static::Simple is designed to work out-of-the-box, you can tweak
311 the operation by adding various configuration options. In a production
312 environment, you will probably want to use your webserver to deliver
313 static content; for an example see L<USING WITH APACHE>, below.
315 =head1 DEFAULT BEHAVIOR
317 By default, Static::Simple will deliver all files having extensions
318 (that is, bits of text following a period (C<.>)), I<except> files
319 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
320 C<xhtml>. These files, and all files without extensions, will be
321 processed through Catalyst. If L<MIME::Types> doesn't recognize an
322 extension, it will be served as C<text/plain>.
324 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
325 and C<xhtml> I<will not> be served statically by default, they will be
326 processed by Catalyst. Thus if you want to use C<.html> files from
327 within a Catalyst app as static files, you need to change the
328 configuration of Static::Simple. Note also that files having any other
329 extension I<will> be served statically, so if you're using any other
330 extension for template files, you should also change the configuration.
332 Logging of static files is turned off by default.
334 =head1 ADVANCED CONFIGURATION
336 Configuration is completely optional and is specified within
337 C<MyApp-E<gt>config-E<gt>{static}>. If you use any of these options,
338 this module will probably feel less "simple" to you!
340 =head2 Enabling request logging
342 Since Catalyst 5.50, logging of static requests is turned off by
343 default; static requests tend to clutter the log output and rarely
344 reveal anything useful. However, if you want to enable logging of static
345 requests, you can do so by setting
346 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{logging}> to 1.
348 =head2 Forcing directories into static mode
350 Define a list of top-level directories beneath your 'root' directory
351 that should always be served in static mode. Regular expressions may be
352 specified using C<qr//>.
354 MyApp->config->{static}->{dirs} = [
359 =head2 Including additional directories
361 You may specify a list of directories in which to search for your static
362 files. The directories will be searched in order and will return the
363 first file found. Note that your root directory is B<not> automatically
364 added to the search path when you specify an C<include_path>. You should
365 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
367 MyApp->config->{static}->{include_path} = [
370 MyApp->config->{root}
373 With the above setting, a request for the file C</images/logo.jpg> will search
374 for the following files, returning the first one found:
376 /path/to/overlay/images/logo.jpg
377 /dynamic/path/images/logo.jpg
378 /your/app/home/root/images/logo.jpg
380 The include path can contain a subroutine reference to dynamically return a
381 list of available directories. This method will receive the C<$c> object as a
382 parameter and should return a reference to a list of directories. Errors can
383 be reported using C<die()>. This method will be called every time a file is
384 requested that appears to be a static file (i.e. it has an extension).
388 sub incpath_generator {
391 if ( $c->session->{customer_dir} ) {
392 return [ $c->session->{customer_dir} ];
394 die "No customer dir defined.";
398 =head2 Ignoring certain types of files
400 There are some file types you may not wish to serve as static files.
401 Most important in this category are your raw template files. By
402 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
403 C<xhtml> will be ignored by Static::Simple in the interest of security.
404 If you wish to define your own extensions to ignore, use the
405 C<ignore_extensions> option:
407 MyApp->config->{static}->{ignore_extensions}
408 = [ qw/html asp php/ ];
410 =head2 Ignoring entire directories
412 To prevent an entire directory from being served statically, you can use
413 the C<ignore_dirs> option. This option contains a list of relative
414 directory paths to ignore. If using C<include_path>, the path will be
415 checked against every included path.
417 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
419 For example, if combined with the above C<include_path> setting, this
420 C<ignore_dirs> value will ignore the following directories if they exist:
422 /path/to/overlay/tmpl
426 /your/app/home/root/tmpl
427 /your/app/home/root/css
429 =head2 Custom MIME types
431 To override or add to the default MIME types set by the L<MIME::Types>
432 module, you may enter your own extension to MIME type mapping.
434 MyApp->config->{static}->{mime_types} = {
439 =head2 Compatibility with other plugins
441 Since version 0.12, Static::Simple plays nice with other plugins. It no
442 longer short-circuits the C<prepare_action> stage as it was causing too
443 many compatibility issues with other plugins.
445 =head2 Debugging information
447 Enable additional debugging information printed in the Catalyst log. This
448 is automatically enabled when running Catalyst in -Debug mode.
450 MyApp->config->{static}->{debug} = 1;
452 =head1 USING WITH APACHE
454 While Static::Simple will work just fine serving files through Catalyst
455 in mod_perl, for increased performance you may wish to have Apache
456 handle the serving of your static files directly. To do this, simply use
457 a dedicated directory for your static files and configure an Apache
458 Location block for that directory This approach is recommended for
459 production installations.
461 <Location /myapp/static>
462 SetHandler default-handler
465 Using this approach Apache will bypass any handling of these directories
466 through Catalyst. You can leave Static::Simple as part of your
467 application, and it will continue to function on a development server,
468 or using Catalyst's built-in server.
470 In practice, your Catalyst application is probably (i.e. should be)
471 structured in the recommended way (i.e., that generated by bootstrapping
472 the application with the C<catalyst.pl> script, with a main directory
473 under which is a C<lib/> directory for module files and a C<root/>
474 directory for templates and static files). Thus, unless you break up
475 this structure when deploying your app by moving the static files to a
476 different location in your filesystem, you will need to use an Alias
477 directive in Apache to point to the right place. You will then need to
478 add a Directory block to give permission for Apache to serve these
479 files. The final configuration will look something like this:
481 Alias /myapp/static /filesystem/path/to/MyApp/root/static
482 <Directory /filesystem/path/to/MyApp/root/static>
485 <Location /myapp/static>
486 SetHandler default-handler
489 If you are running in a VirtualHost, you can just set the DocumentRoot
490 location to the location of your root directory; see
491 L<Catalyst::Engine::Apache2::MP20>.
493 =head1 PUBLIC METHODS
495 =head2 serve_static_file $file_path
497 Will serve the file located in $file_path statically. This is useful when
498 you need to autogenerate them if they don't exist, or they are stored in a model.
500 package MyApp::Controller::User;
502 sub curr_user_thumb : PathPart("my_thumbnail.png") {
503 my ( $self, $c ) = @_;
504 my $file_path = $c->user->picture_thumbnail_path;
505 $c->serve_static_file($file_path);
508 =head1 INTERNAL EXTENDED METHODS
510 Static::Simple extends the following steps in the Catalyst process.
512 =head2 prepare_action
514 C<prepare_action> is used to first check if the request path is a static
515 file. If so, we skip all other C<prepare_action> steps to improve
520 C<dispatch> takes the file found during C<prepare_action> and writes it
525 C<finalize> serves up final header information and displays any log
530 C<setup> initializes all default values.
534 L<Catalyst>, L<Catalyst::Plugin::Static>,
535 L<http://www.iana.org/assignments/media-types/>
539 Andy Grundman, <andy@hybridized.org>
543 Marcus Ramberg, <mramberg@cpan.org>
545 Jesse Sheidlower, <jester@panix.com>
547 Guillermo Roditi, <groditi@cpan.org>
549 Florian Ragwitz, <rafl@debian.org>
551 Tomas Doran, <bobtfish@bobtfish.net>
557 The authors of Catalyst::Plugin::Static:
563 For the include_path code from Template Toolkit:
569 Copyright (c) 2005 - 2009
570 the Catalyst::Plugin::Static::Simple L</AUTHOR> and L</CONTRIBUTORS>
575 This program is free software, you can redistribute it and/or modify it under
576 the same terms as Perl itself.