1 package Catalyst::Plugin::Static::Simple;
5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
12 our $VERSION = '0.23';
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
30 my $re = ( $dir =~ m{^qr/}xms ) ? eval $dir : qr{^${dir_re}/};
32 $c->error( "Error compiling static dir regex '$dir': $@" );
35 if ( $c->_locate_static_file( $path, 1 ) ) {
36 $c->_debug_msg( 'from static directory' )
39 $c->_debug_msg( "404: file not found: $path" )
41 $c->res->status( 404 );
42 $c->res->content_type( 'text/html' );
47 # Does the path have an extension?
48 if ( $path =~ /.*\.(\S{1,})$/xms ) {
50 $c->_locate_static_file( $path );
53 return $c->next::method(@_);
59 return if ( $c->res->status != 200 );
61 if ( $c->_static_file ) {
62 if ( $c->config->{static}{no_logs} && $c->log->can('abort') ) {
65 return $c->_serve_static;
68 return $c->next::method(@_);
75 # display all log messages
76 if ( $c->config->{static}{debug} && scalar @{$c->_debug_msg} ) {
77 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
80 return $c->next::method(@_);
86 $c->maybe::next::method(@_);
88 my $config = $c->config->{static} ||= {};
90 $config->{dirs} ||= [];
91 $config->{include_path} ||= [ $c->config->{root} ];
92 $config->{mime_types} ||= {};
93 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
94 $config->{ignore_dirs} ||= [];
95 $config->{debug} ||= $c->debug;
96 $config->{no_logs} = 1 unless defined $config->{no_logs};
97 $config->{no_logs} = 0 if $config->{logging};
99 # load up a MIME::Types object, only loading types with
100 # at least 1 file extension
101 $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
103 # preload the type index hash so it's not built on the first request
104 $config->{mime_types_obj}->create_type_index;
107 # Search through all included directories for the static file
108 # Based on Template Toolkit INCLUDE_PATH code
109 sub _locate_static_file {
110 my ( $c, $path, $in_static_dir ) = @_;
112 $path = File::Spec->catdir(
113 File::Spec->no_upwards( File::Spec->splitdir( $path ) )
116 my $config = $c->config->{static};
117 my @ipaths = @{ $config->{include_path} };
119 my $count = 64; # maximum number of directories to search
122 while ( @ipaths && --$count) {
123 my $dir = shift @ipaths || next DIR_CHECK;
125 if ( ref $dir eq 'CODE' ) {
126 eval { $dpaths = &$dir( $c ) };
128 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
130 unshift @ipaths, @$dpaths;
134 $dir =~ s/(\/|\\)$//xms;
135 if ( -d $dir && -f $dir . '/' . $path ) {
137 # Don't ignore any files in static dirs defined with 'dirs'
138 unless ( $in_static_dir ) {
139 # do we need to ignore the file?
140 for my $ignore ( @{ $config->{ignore_dirs} } ) {
141 $ignore =~ s{(/|\\)$}{};
142 if ( $path =~ /^$ignore(\/|\\)/ ) {
143 $c->_debug_msg( "Ignoring directory `$ignore`" )
149 # do we need to ignore based on extension?
150 for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
151 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
152 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
159 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
161 return $c->_static_file( $dir . '/' . $path );
172 my $full_path = shift || $c->_static_file;
173 my $type = $c->_ext_to_type( $full_path );
174 my $stat = stat $full_path;
176 $c->res->headers->content_type( $type );
177 $c->res->headers->content_length( $stat->size );
178 $c->res->headers->last_modified( $stat->mtime );
180 my $fh = IO::File->new( $full_path, 'r' );
183 $c->res->body( $fh );
186 Catalyst::Exception->throw(
187 message => "Unable to open $full_path for reading" );
193 sub serve_static_file {
194 my ( $c, $full_path ) = @_;
196 my $config = $c->config->{static} ||= {};
198 if ( -e $full_path ) {
199 $c->_debug_msg( "Serving static file: $full_path" )
203 $c->_debug_msg( "404: file not found: $full_path" )
205 $c->res->status( 404 );
206 $c->res->content_type( 'text/html' );
210 $c->_serve_static( $full_path );
213 # looks up the correct MIME type for the current file extension
215 my ( $c, $full_path ) = @_;
217 my $config = $c->config->{static};
219 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
221 my $type = $config->{mime_types}{$ext}
222 || $config->{mime_types_obj}->mimeTypeOf( $ext );
224 $c->_debug_msg( "as $type" ) if $config->{debug};
225 return ( ref $type ) ? $type->type : $type;
228 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
234 $c->_debug_msg( 'as text/plain (no extension)' )
241 my ( $c, $msg ) = @_;
243 if ( !defined $c->_static_debug_message ) {
244 $c->_static_debug_message( [] );
248 push @{ $c->_static_debug_message }, $msg;
251 return $c->_static_debug_message;
259 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
264 use Catalyst qw/ Static::Simple /;
266 # that's it; static content is automatically served by Catalyst
267 # from the application's root directory, though you can configure
268 # things or bypass Catalyst entirely in a production environment
270 # one caveat: the files must be served from an absolute path
271 # (i.e. /images/foo.png)
275 The Static::Simple plugin is designed to make serving static content in
276 your application during development quick and easy, without requiring a
277 single line of code from you.
279 This plugin detects static files by looking at the file extension in the
280 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
281 lightweight L<MIME::Types> module to map file extensions to
282 IANA-registered MIME types, and will serve your static files with the
283 correct MIME type directly to the browser, without being processed
286 Note that actions mapped to paths using periods (.) will still operate
289 If the plugin can not find the file, the request is dispatched to your
290 application instead. This means you are responsible for generating a
291 C<404> error if your applicaton can not process the request:
293 # handled by static::simple, not dispatched to your application
296 # static::simple will not find the file and let your application
297 # handle the request. You are responsible for generating a file
298 # or returning a 404 error
299 /images/does_not_exist.png
301 Though Static::Simple is designed to work out-of-the-box, you can tweak
302 the operation by adding various configuration options. In a production
303 environment, you will probably want to use your webserver to deliver
304 static content; for an example see L<USING WITH APACHE>, below.
306 =head1 DEFAULT BEHAVIOR
308 By default, Static::Simple will deliver all files having extensions
309 (that is, bits of text following a period (C<.>)), I<except> files
310 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
311 C<xhtml>. These files, and all files without extensions, will be
312 processed through Catalyst. If L<MIME::Types> doesn't recognize an
313 extension, it will be served as C<text/plain>.
315 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
316 and C<xhtml> I<will not> be served statically by default, they will be
317 processed by Catalyst. Thus if you want to use C<.html> files from
318 within a Catalyst app as static files, you need to change the
319 configuration of Static::Simple. Note also that files having any other
320 extension I<will> be served statically, so if you're using any other
321 extension for template files, you should also change the configuration.
323 Logging of static files is turned off by default.
325 =head1 ADVANCED CONFIGURATION
327 Configuration is completely optional and is specified within
328 C<MyApp-E<gt>config-E<gt>{static}>. If you use any of these options,
329 this module will probably feel less "simple" to you!
331 =head2 Enabling request logging
333 Since Catalyst 5.50, logging of static requests is turned off by
334 default; static requests tend to clutter the log output and rarely
335 reveal anything useful. However, if you want to enable logging of static
336 requests, you can do so by setting
337 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{logging}> to 1.
339 =head2 Forcing directories into static mode
341 Define a list of top-level directories beneath your 'root' directory
342 that should always be served in static mode. Regular expressions may be
343 specified using C<qr//>.
345 MyApp->config->{static}->{dirs} = [
350 =head2 Including additional directories
352 You may specify a list of directories in which to search for your static
353 files. The directories will be searched in order and will return the
354 first file found. Note that your root directory is B<not> automatically
355 added to the search path when you specify an C<include_path>. You should
356 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
358 MyApp->config->{static}->{include_path} = [
361 MyApp->config->{root}
364 With the above setting, a request for the file C</images/logo.jpg> will search
365 for the following files, returning the first one found:
367 /path/to/overlay/images/logo.jpg
368 /dynamic/path/images/logo.jpg
369 /your/app/home/root/images/logo.jpg
371 The include path can contain a subroutine reference to dynamically return a
372 list of available directories. This method will receive the C<$c> object as a
373 parameter and should return a reference to a list of directories. Errors can
374 be reported using C<die()>. This method will be called every time a file is
375 requested that appears to be a static file (i.e. it has an extension).
379 sub incpath_generator {
382 if ( $c->session->{customer_dir} ) {
383 return [ $c->session->{customer_dir} ];
385 die "No customer dir defined.";
389 =head2 Ignoring certain types of files
391 There are some file types you may not wish to serve as static files.
392 Most important in this category are your raw template files. By
393 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
394 C<xhtml> will be ignored by Static::Simple in the interest of security.
395 If you wish to define your own extensions to ignore, use the
396 C<ignore_extensions> option:
398 MyApp->config->{static}->{ignore_extensions}
399 = [ qw/html asp php/ ];
401 =head2 Ignoring entire directories
403 To prevent an entire directory from being served statically, you can use
404 the C<ignore_dirs> option. This option contains a list of relative
405 directory paths to ignore. If using C<include_path>, the path will be
406 checked against every included path.
408 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
410 For example, if combined with the above C<include_path> setting, this
411 C<ignore_dirs> value will ignore the following directories if they exist:
413 /path/to/overlay/tmpl
417 /your/app/home/root/tmpl
418 /your/app/home/root/css
420 =head2 Custom MIME types
422 To override or add to the default MIME types set by the L<MIME::Types>
423 module, you may enter your own extension to MIME type mapping.
425 MyApp->config->{static}->{mime_types} = {
430 =head2 Compatibility with other plugins
432 Since version 0.12, Static::Simple plays nice with other plugins. It no
433 longer short-circuits the C<prepare_action> stage as it was causing too
434 many compatibility issues with other plugins.
436 =head2 Debugging information
438 Enable additional debugging information printed in the Catalyst log. This
439 is automatically enabled when running Catalyst in -Debug mode.
441 MyApp->config->{static}->{debug} = 1;
443 =head1 USING WITH APACHE
445 While Static::Simple will work just fine serving files through Catalyst
446 in mod_perl, for increased performance you may wish to have Apache
447 handle the serving of your static files directly. To do this, simply use
448 a dedicated directory for your static files and configure an Apache
449 Location block for that directory This approach is recommended for
450 production installations.
452 <Location /myapp/static>
453 SetHandler default-handler
456 Using this approach Apache will bypass any handling of these directories
457 through Catalyst. You can leave Static::Simple as part of your
458 application, and it will continue to function on a development server,
459 or using Catalyst's built-in server.
461 In practice, your Catalyst application is probably (i.e. should be)
462 structured in the recommended way (i.e., that generated by bootstrapping
463 the application with the C<catalyst.pl> script, with a main directory
464 under which is a C<lib/> directory for module files and a C<root/>
465 directory for templates and static files). Thus, unless you break up
466 this structure when deploying your app by moving the static files to a
467 different location in your filesystem, you will need to use an Alias
468 directive in Apache to point to the right place. You will then need to
469 add a Directory block to give permission for Apache to serve these
470 files. The final configuration will look something like this:
472 Alias /myapp/static /filesystem/path/to/MyApp/root/static
473 <Directory /filesystem/path/to/MyApp/root/static>
476 <Location /myapp/static>
477 SetHandler default-handler
480 If you are running in a VirtualHost, you can just set the DocumentRoot
481 location to the location of your root directory; see
482 L<Catalyst::Engine::Apache2::MP20>.
484 =head1 PUBLIC METHODS
486 =head2 serve_static_file $file_path
488 Will serve the file located in $file_path statically. This is useful when
489 you need to autogenerate them if they don't exist, or they are stored in a model.
491 package MyApp::Controller::User;
493 sub curr_user_thumb : PathPart("my_thumbnail.png") {
494 my ( $self, $c ) = @_;
495 my $file_path = $c->user->picture_thumbnail_path;
496 $c->serve_static_file($file_path);
499 =head1 INTERNAL EXTENDED METHODS
501 Static::Simple extends the following steps in the Catalyst process.
503 =head2 prepare_action
505 C<prepare_action> is used to first check if the request path is a static
506 file. If so, we skip all other C<prepare_action> steps to improve
511 C<dispatch> takes the file found during C<prepare_action> and writes it
516 C<finalize> serves up final header information and displays any log
521 C<setup> initializes all default values.
525 L<Catalyst>, L<Catalyst::Plugin::Static>,
526 L<http://www.iana.org/assignments/media-types/>
530 Andy Grundman, <andy@hybridized.org>
534 Marcus Ramberg, <mramberg@cpan.org>
536 Jesse Sheidlower, <jester@panix.com>
538 Guillermo Roditi, <groditi@cpan.org>
540 Florian Ragwitz <rafl@debian.org>
544 The authors of Catalyst::Plugin::Static:
550 For the include_path code from Template Toolkit:
556 This program is free software, you can redistribute it and/or modify it under
557 the same terms as Perl itself.