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/ );
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 if ( Catalyst->VERSION le '5.33' ) {
92 my $config = $c->config->{static} ||= {};
94 $config->{dirs} ||= [];
95 $config->{include_path} ||= [ $c->config->{root} ];
96 $config->{mime_types} ||= {};
97 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
98 $config->{ignore_dirs} ||= [];
99 $config->{debug} ||= $c->debug;
100 $config->{no_logs} = 1 unless defined $config->{no_logs};
101 $config->{no_logs} = 0 if $config->{logging};
103 # load up a MIME::Types object, only loading types with
104 # at least 1 file extension
105 $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
107 # preload the type index hash so it's not built on the first request
108 $config->{mime_types_obj}->create_type_index;
111 # Search through all included directories for the static file
112 # Based on Template Toolkit INCLUDE_PATH code
113 sub _locate_static_file {
114 my ( $c, $path, $in_static_dir ) = @_;
116 $path = File::Spec->catdir(
117 File::Spec->no_upwards( File::Spec->splitdir( $path ) )
120 my $config = $c->config->{static};
121 my @ipaths = @{ $config->{include_path} };
123 my $count = 64; # maximum number of directories to search
126 while ( @ipaths && --$count) {
127 my $dir = shift @ipaths || next DIR_CHECK;
129 if ( ref $dir eq 'CODE' ) {
130 eval { $dpaths = &$dir( $c ) };
132 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
134 unshift @ipaths, @$dpaths;
138 $dir =~ s/(\/|\\)$//xms;
139 if ( -d $dir && -f $dir . '/' . $path ) {
141 # Don't ignore any files in static dirs defined with 'dirs'
142 unless ( $in_static_dir ) {
143 # do we need to ignore the file?
144 for my $ignore ( @{ $config->{ignore_dirs} } ) {
145 $ignore =~ s{(/|\\)$}{};
146 if ( $path =~ /^$ignore(\/|\\)/ ) {
147 $c->_debug_msg( "Ignoring directory `$ignore`" )
153 # do we need to ignore based on extension?
154 for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
155 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
156 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
163 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
165 return $c->_static_file( $dir . '/' . $path );
176 my $full_path = shift || $c->_static_file;
177 my $type = $c->_ext_to_type( $full_path );
178 my $stat = stat $full_path;
180 $c->res->headers->content_type( $type );
181 $c->res->headers->content_length( $stat->size );
182 $c->res->headers->last_modified( $stat->mtime );
184 if ( Catalyst->VERSION le '5.33' ) {
185 # old File::Slurp method
186 my $content = File::Slurp::read_file( $full_path );
187 $c->res->body( $content );
190 # new method, pass an IO::File object to body
191 my $fh = IO::File->new( $full_path, 'r' );
194 $c->res->body( $fh );
197 Catalyst::Exception->throw(
198 message => "Unable to open $full_path for reading" );
205 sub serve_static_file {
206 my ( $c, $full_path ) = @_;
208 my $config = $c->config->{static} ||= {};
210 if ( -e $full_path ) {
211 $c->_debug_msg( "Serving static file: $full_path" )
215 $c->_debug_msg( "404: file not found: $full_path" )
217 $c->res->status( 404 );
218 $c->res->content_type( 'text/html' );
222 $c->_serve_static( $full_path );
225 # looks up the correct MIME type for the current file extension
227 my ( $c, $full_path ) = @_;
229 my $config = $c->config->{static};
231 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
233 my $type = $config->{mime_types}{$ext}
234 || $config->{mime_types_obj}->mimeTypeOf( $ext );
236 $c->_debug_msg( "as $type" ) if $config->{debug};
237 return ( ref $type ) ? $type->type : $type;
240 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
246 $c->_debug_msg( 'as text/plain (no extension)' )
253 my ( $c, $msg ) = @_;
255 if ( !defined $c->_static_debug_message ) {
256 $c->_static_debug_message( [] );
260 push @{ $c->_static_debug_message }, $msg;
263 return $c->_static_debug_message;
271 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
276 MyApp->setup( qw/Static::Simple/ );
277 # that's it; static content is automatically served by Catalyst
278 # from the application's root directory, though you can configure
279 # things or bypass Catalyst entirely in a production environment
281 # one caveat: the files must be served from an absolute path
282 # (i.e. /images/foo.png)
286 The Static::Simple plugin is designed to make serving static content in
287 your application during development quick and easy, without requiring a
288 single line of code from you.
290 This plugin detects static files by looking at the file extension in the
291 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
292 lightweight L<MIME::Types> module to map file extensions to
293 IANA-registered MIME types, and will serve your static files with the
294 correct MIME type directly to the browser, without being processed
297 Note that actions mapped to paths using periods (.) will still operate
300 Though Static::Simple is designed to work out-of-the-box, you can tweak
301 the operation by adding various configuration options. In a production
302 environment, you will probably want to use your webserver to deliver
303 static content; for an example see L<USING WITH APACHE>, below.
305 =head1 DEFAULT BEHAVIOR
307 By default, Static::Simple will deliver all files having extensions
308 (that is, bits of text following a period (C<.>)), I<except> files
309 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
310 C<xhtml>. These files, and all files without extensions, will be
311 processed through Catalyst. If L<MIME::Types> doesn't recognize an
312 extension, it will be served as C<text/plain>.
314 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
315 and C<xhtml> I<will not> be served statically by default, they will be
316 processed by Catalyst. Thus if you want to use C<.html> files from
317 within a Catalyst app as static files, you need to change the
318 configuration of Static::Simple. Note also that files having any other
319 extension I<will> be served statically, so if you're using any other
320 extension for template files, you should also change the configuration.
322 Logging of static files is turned off by default.
324 =head1 ADVANCED CONFIGURATION
326 Configuration is completely optional and is specified within
327 C<MyApp-E<gt>config-E<gt>{static}>. If you use any of these options,
328 this module will probably feel less "simple" to you!
330 =head2 Enabling request logging
332 Since Catalyst 5.50, logging of static requests is turned off by
333 default; static requests tend to clutter the log output and rarely
334 reveal anything useful. However, if you want to enable logging of static
335 requests, you can do so by setting
336 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{logging}> to 1.
338 =head2 Forcing directories into static mode
340 Define a list of top-level directories beneath your 'root' directory
341 that should always be served in static mode. Regular expressions may be
342 specified using C<qr//>.
344 MyApp->config->{static}->{dirs} = [
349 =head2 Including additional directories
351 You may specify a list of directories in which to search for your static
352 files. The directories will be searched in order and will return the
353 first file found. Note that your root directory is B<not> automatically
354 added to the search path when you specify an C<include_path>. You should
355 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
357 MyApp->config->{static}->{include_path} = [
360 MyApp->config->{root}
363 With the above setting, a request for the file C</images/logo.jpg> will search
364 for the following files, returning the first one found:
366 /path/to/overlay/images/logo.jpg
367 /dynamic/path/images/logo.jpg
368 /your/app/home/root/images/logo.jpg
370 The include path can contain a subroutine reference to dynamically return a
371 list of available directories. This method will receive the C<$c> object as a
372 parameter and should return a reference to a list of directories. Errors can
373 be reported using C<die()>. This method will be called every time a file is
374 requested that appears to be a static file (i.e. it has an extension).
378 sub incpath_generator {
381 if ( $c->session->{customer_dir} ) {
382 return [ $c->session->{customer_dir} ];
384 die "No customer dir defined.";
388 =head2 Ignoring certain types of files
390 There are some file types you may not wish to serve as static files.
391 Most important in this category are your raw template files. By
392 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
393 C<xhtml> will be ignored by Static::Simple in the interest of security.
394 If you wish to define your own extensions to ignore, use the
395 C<ignore_extensions> option:
397 MyApp->config->{static}->{ignore_extensions}
398 = [ qw/html asp php/ ];
400 =head2 Ignoring entire directories
402 To prevent an entire directory from being served statically, you can use
403 the C<ignore_dirs> option. This option contains a list of relative
404 directory paths to ignore. If using C<include_path>, the path will be
405 checked against every included path.
407 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
409 For example, if combined with the above C<include_path> setting, this
410 C<ignore_dirs> value will ignore the following directories if they exist:
412 /path/to/overlay/tmpl
416 /your/app/home/root/tmpl
417 /your/app/home/root/css
419 =head2 Custom MIME types
421 To override or add to the default MIME types set by the L<MIME::Types>
422 module, you may enter your own extension to MIME type mapping.
424 MyApp->config->{static}->{mime_types} = {
429 =head2 Compatibility with other plugins
431 Since version 0.12, Static::Simple plays nice with other plugins. It no
432 longer short-circuits the C<prepare_action> stage as it was causing too
433 many compatibility issues with other plugins.
435 =head2 Debugging information
437 Enable additional debugging information printed in the Catalyst log. This
438 is automatically enabled when running Catalyst in -Debug mode.
440 MyApp->config->{static}->{debug} = 1;
442 =head1 USING WITH APACHE
444 While Static::Simple will work just fine serving files through Catalyst
445 in mod_perl, for increased performance you may wish to have Apache
446 handle the serving of your static files directly. To do this, simply use
447 a dedicated directory for your static files and configure an Apache
448 Location block for that directory This approach is recommended for
449 production installations.
451 <Location /myapp/static>
452 SetHandler default-handler
455 Using this approach Apache will bypass any handling of these directories
456 through Catalyst. You can leave Static::Simple as part of your
457 application, and it will continue to function on a development server,
458 or using Catalyst's built-in server.
460 In practice, your Catalyst application is probably (i.e. should be)
461 structured in the recommended way (i.e., that generated by bootstrapping
462 the application with the C<catalyst.pl> script, with a main directory
463 under which is a C<lib/> directory for module files and a C<root/>
464 directory for templates and static files). Thus, unless you break up
465 this structure when deploying your app by moving the static files to a
466 different location in your filesystem, you will need to use an Alias
467 directive in Apache to point to the right place. You will then need to
468 add a Directory block to give permission for Apache to serve these
469 files. The final configuration will look something like this:
471 Alias /myapp/static /filesystem/path/to/MyApp/root/static
472 <Directory /filesystem/path/to/MyApp/root/static>
475 <Location /myapp/static>
476 SetHandler default-handler
479 If you are running in a VirtualHost, you can just set the DocumentRoot
480 location to the location of your root directory; see
481 L<Catalyst::Engine::Apache2::MP20>.
483 =head1 PUBLIC METHODS
485 =head2 serve_static_file $file_path
487 Will serve the file located in $file_path statically. This is useful when
488 you need to autogenerate them if they don't exist, or they are stored in a model.
490 package MyApp::Controller::User;
492 sub curr_user_thumb : PathPart("my_thumbnail.png") {
493 my ( $self, $c ) = @_;
494 my $file_path = $c->user->picture_thumbnail_path;
495 $c->serve_static_file($file_path);
498 =head1 INTERNAL EXTENDED METHODS
500 Static::Simple extends the following steps in the Catalyst process.
502 =head2 prepare_action
504 C<prepare_action> is used to first check if the request path is a static
505 file. If so, we skip all other C<prepare_action> steps to improve
510 C<dispatch> takes the file found during C<prepare_action> and writes it
515 C<finalize> serves up final header information and displays any log
520 C<setup> initializes all default values.
524 L<Catalyst>, L<Catalyst::Plugin::Static>,
525 L<http://www.iana.org/assignments/media-types/>
529 Andy Grundman, <andy@hybridized.org>
533 Marcus Ramberg, <mramberg@cpan.org>
535 Jesse Sheidlower, <jester@panix.com>
537 Guillermo Roditi, <groditi@cpan.org>
541 The authors of Catalyst::Plugin::Static:
547 For the include_path code from Template Toolkit:
553 This program is free software, you can redistribute it and/or modify it under
554 the same terms as Perl itself.