1 package Catalyst::Plugin::Static::Simple;
5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
11 our $VERSION = '0.17';
13 __PACKAGE__->mk_accessors( qw/_static_file _static_debug_message/ );
17 my $path = $c->req->path;
18 my $config = $c->config->{static};
20 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
22 # is the URI in a static-defined path?
23 foreach my $dir ( @{ $config->{dirs} } ) {
24 my $dir_re = quotemeta $dir;
25 my $re = ( $dir =~ m{^qr/}xms ) ? eval $dir : qr/^${dir_re}/;
27 $c->error( "Error compiling static dir regex '$dir': $@" );
30 if ( $c->_locate_static_file( $path, 1 ) ) {
31 $c->_debug_msg( 'from static directory' )
34 $c->_debug_msg( "404: file not found: $path" )
36 $c->res->status( 404 );
41 # Does the path have an extension?
42 if ( $path =~ /.*\.(\S{1,})$/xms ) {
44 $c->_locate_static_file( $path );
47 return $c->NEXT::ACTUAL::prepare_action(@_);
53 return if ( $c->res->status != 200 );
55 if ( $c->_static_file ) {
56 if ( $c->config->{static}{no_logs} && $c->log->can('abort') ) {
59 return $c->_serve_static;
62 return $c->NEXT::ACTUAL::dispatch(@_);
69 # display all log messages
70 if ( $c->config->{static}{debug} && scalar @{$c->_debug_msg} ) {
71 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
74 return $c->NEXT::ACTUAL::finalize(@_);
82 if ( Catalyst->VERSION le '5.33' ) {
86 my $config = $c->config->{static} ||= {};
88 $config->{dirs} ||= [];
89 $config->{include_path} ||= [ $c->config->{root} ];
90 $config->{mime_types} ||= {};
91 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
92 $config->{ignore_dirs} ||= [];
93 $config->{debug} ||= $c->debug;
94 $config->{no_logs} = 1 unless defined $config->{no_logs};
96 # load up a MIME::Types object, only loading types with
97 # at least 1 file extension
98 $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
100 # preload the type index hash so it's not built on the first request
101 $config->{mime_types_obj}->create_type_index;
104 # Search through all included directories for the static file
105 # Based on Template Toolkit INCLUDE_PATH code
106 sub _locate_static_file {
107 my ( $c, $path, $in_static_dir ) = @_;
109 $path = File::Spec->catdir(
110 File::Spec->no_upwards( File::Spec->splitdir( $path ) )
113 my $config = $c->config->{static};
114 my @ipaths = @{ $config->{include_path} };
116 my $count = 64; # maximum number of directories to search
119 while ( @ipaths && --$count) {
120 my $dir = shift @ipaths || next DIR_CHECK;
122 if ( ref $dir eq 'CODE' ) {
123 eval { $dpaths = &$dir( $c ) };
125 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
127 unshift @ipaths, @$dpaths;
131 $dir =~ s/(\/|\\)$//xms;
132 if ( -d $dir && -f $dir . '/' . $path ) {
134 # Don't ignore any files in static dirs defined with 'dirs'
135 unless ( $in_static_dir ) {
136 # do we need to ignore the file?
137 for my $ignore ( @{ $config->{ignore_dirs} } ) {
138 $ignore =~ s{(/|\\)$}{};
139 if ( $path =~ /^$ignore(\/|\\)/ ) {
140 $c->_debug_msg( "Ignoring directory `$ignore`" )
146 # do we need to ignore based on extension?
147 for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
148 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
149 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
156 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
158 return $c->_static_file( $dir . '/' . $path );
169 my $full_path = shift || $c->_static_file;
170 my $type = $c->_ext_to_type( $full_path );
171 my $stat = stat $full_path;
173 $c->res->headers->content_type( $type );
174 $c->res->headers->content_length( $stat->size );
175 $c->res->headers->last_modified( $stat->mtime );
177 if ( Catalyst->VERSION le '5.33' ) {
178 # old File::Slurp method
179 my $content = File::Slurp::read_file( $full_path );
180 $c->res->body( $content );
183 # new method, pass an IO::File object to body
184 my $fh = IO::File->new( $full_path, 'r' );
187 $c->res->body( $fh );
190 Catalyst::Exception->throw(
191 message => "Unable to open $full_path for reading" );
198 sub serve_static_file {
199 my ( $c, $full_path ) = @_;
201 my $config = $c->config->{static} ||= {};
203 if ( -e $full_path ) {
204 $c->_debug_msg( "Serving static file: $full_path" )
208 $c->_debug_msg( "404: file not found: $full_path" )
210 $c->res->status( 404 );
214 $c->_serve_static( $full_path );
217 # looks up the correct MIME type for the current file extension
219 my ( $c, $full_path ) = @_;
221 my $config = $c->config->{static};
223 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
225 my $type = $config->{mime_types}{$ext}
226 || $config->{mime_types_obj}->mimeTypeOf( $ext );
228 $c->_debug_msg( "as $type" ) if $config->{debug};
229 return ( ref $type ) ? $type->type : $type;
232 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
238 $c->_debug_msg( 'as text/plain (no extension)' )
245 my ( $c, $msg ) = @_;
247 if ( !defined $c->_static_debug_message ) {
248 $c->_static_debug_message( [] );
252 push @{ $c->_static_debug_message }, $msg;
255 return $c->_static_debug_message;
263 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
268 MyApp->setup( qw/Static::Simple/ );
269 # that's it; static content is automatically served by
270 # Catalyst, though you can configure things or bypass
271 # Catalyst entirely in a production environment
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 Though Static::Simple is designed to work out-of-the-box, you can tweak
290 the operation by adding various configuration options. In a production
291 environment, you will probably want to use your webserver to deliver
292 static content; for an example see L<USING WITH APACHE>, below.
294 =head1 DEFAULT BEHAVIOR
296 By default, Static::Simple will deliver all files having extensions
297 (that is, bits of text following a period (C<.>)), I<except> files
298 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
299 C<xhtml>. These files, and all files without extensions, will be
300 processed through Catalyst. If L<MIME::Types> doesn't recognize an
301 extension, it will be served as C<text/plain>.
303 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
304 and C<xhtml> I<will not> be served statically by default, they will be
305 processed by Catalyst. Thus if you want to use C<.html> files from
306 within a Catalyst app as static files, you need to change the
307 configuration of Static::Simple. Note also that files having any other
308 extension I<will> be served statically, so if you're using any other
309 extension for template files, you should also change the configuration.
311 Logging of static files is turned off by default.
313 =head1 ADVANCED CONFIGURATION
315 Configuration is completely optional and is specified within
316 C<MyApp-E<gt>config-E<gt>{static}>. If you use any of these options,
317 this module will probably feel less "simple" to you!
319 =head2 Enabling request logging
321 Since Catalyst 5.50, logging of static requests is turned off by
322 default; static requests tend to clutter the log output and rarely
323 reveal anything useful. However, if you want to enable logging of static
324 requests, you can do so by setting
325 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{no_logs}> to 0.
327 =head2 Forcing directories into static mode
329 Define a list of top-level directories beneath your 'root' directory
330 that should always be served in static mode. Regular expressions may be
331 specified using C<qr//>.
333 MyApp->config->{static}->{dirs} = [
338 =head2 Including additional directories
340 You may specify a list of directories in which to search for your static
341 files. The directories will be searched in order and will return the
342 first file found. Note that your root directory is B<not> automatically
343 added to the search path when you specify an C<include_path>. You should
344 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
346 MyApp->config->{static}->{include_path} = [
349 MyApp->config->{root}
352 With the above setting, a request for the file C</images/logo.jpg> will search
353 for the following files, returning the first one found:
355 /path/to/overlay/images/logo.jpg
356 /dynamic/path/images/logo.jpg
357 /your/app/home/root/images/logo.jpg
359 The include path can contain a subroutine reference to dynamically return a
360 list of available directories. This method will receive the C<$c> object as a
361 parameter and should return a reference to a list of directories. Errors can
362 be reported using C<die()>. This method will be called every time a file is
363 requested that appears to be a static file (i.e. it has an extension).
367 sub incpath_generator {
370 if ( $c->session->{customer_dir} ) {
371 return [ $c->session->{customer_dir} ];
373 die "No customer dir defined.";
377 =head2 Ignoring certain types of files
379 There are some file types you may not wish to serve as static files.
380 Most important in this category are your raw template files. By
381 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
382 C<xhtml> will be ignored by Static::Simple in the interest of security.
383 If you wish to define your own extensions to ignore, use the
384 C<ignore_extensions> option:
386 MyApp->config->{static}->{ignore_extensions}
387 = [ qw/html asp php/ ];
389 =head2 Ignoring entire directories
391 To prevent an entire directory from being served statically, you can use
392 the C<ignore_dirs> option. This option contains a list of relative
393 directory paths to ignore. If using C<include_path>, the path will be
394 checked against every included path.
396 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
398 For example, if combined with the above C<include_path> setting, this
399 C<ignore_dirs> value will ignore the following directories if they exist:
401 /path/to/overlay/tmpl
405 /your/app/home/root/tmpl
406 /your/app/home/root/css
408 =head2 Custom MIME types
410 To override or add to the default MIME types set by the L<MIME::Types>
411 module, you may enter your own extension to MIME type mapping.
413 MyApp->config->{static}->{mime_types} = {
418 =head2 Compatibility with other plugins
420 Since version 0.12, Static::Simple plays nice with other plugins. It no
421 longer short-circuits the C<prepare_action> stage as it was causing too
422 many compatibility issues with other plugins.
424 =head2 Debugging information
426 Enable additional debugging information printed in the Catalyst log. This
427 is automatically enabled when running Catalyst in -Debug mode.
429 MyApp->config->{static}->{debug} = 1;
431 =head1 USING WITH APACHE
433 While Static::Simple will work just fine serving files through Catalyst in
434 mod_perl, for increased performance, you may wish to have Apache handle the
435 serving of your static files. To do this, simply use a dedicated directory
436 for your static files and configure an Apache Location block for that
437 directory. This approach is recommended for production installations.
440 SetHandler default-handler
443 Using this approach Apache will bypass any handling of these directories
444 through Catalyst. You can leave Static::Simple as part of your
445 application, and it will continue to function on a development server,
446 or using Catalyst's built-in server.
448 =head1 PUBLIC METHODS
450 =head2 serve_static_file $file_path
452 Will serve the file located in $file_path statically. This is useful when
453 you need to autogenerate them if they don't exist, or they are stored in a model.
455 package MyApp::Controller::User;
457 sub curr_user_thumb : PathPart("my_thumbnail.png") {
458 my ( $self, $c ) = @_;
459 my $file_path = $c->user->picture_thumbnail_path;
460 $c->serve_static_file($file_path);
463 =head1 INTERNAL EXTENDED METHODS
465 Static::Simple extends the following steps in the Catalyst process.
467 =head2 prepare_action
469 C<prepare_action> is used to first check if the request path is a static
470 file. If so, we skip all other C<prepare_action> steps to improve
475 C<dispatch> takes the file found during C<prepare_action> and writes it
480 C<finalize> serves up final header information and displays any log
485 C<setup> initializes all default values.
489 L<Catalyst>, L<Catalyst::Plugin::Static>,
490 L<http://www.iana.org/assignments/media-types/>
494 Andy Grundman, <andy@hybridized.org>
498 Marcus Ramberg, <mramberg@cpan.org>
500 Jesse Sheidlower, <jester@panix.com>
502 Guillermo Roditi, <groditi@cpan.org>
506 The authors of Catalyst::Plugin::Static:
512 For the include_path code from Template Toolkit:
518 This program is free software, you can redistribute it and/or modify it under
519 the same terms as Perl itself.