1 package Catalyst::Plugin::Static::Simple;
8 use MooseX::Types::Moose qw/ArrayRef Str/;
9 use namespace::autoclean;
11 our $VERSION = '0.28';
13 has _static_file => ( is => 'rw' );
14 has _static_debug_message => ( is => 'rw', isa => ArrayRef[Str] );
16 before prepare_action => sub {
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 );
63 override dispatch => sub {
66 return if ( $c->res->status != 200 );
68 if ( $c->_static_file ) {
69 if ( $c->config->{static}{no_logs} && $c->log->can('abort') ) {
72 return $c->_serve_static;
79 before finalize => sub {
82 # display all log messages
83 if ( $c->config->{static}{debug} && scalar @{$c->_debug_msg} ) {
84 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
88 before setup_finalize => sub {
91 my $config = $c->config->{static} ||= {};
93 $config->{dirs} ||= [];
94 $config->{include_path} ||= [ $c->config->{root} ];
95 $config->{mime_types} ||= {};
96 $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
97 $config->{ignore_dirs} ||= [];
98 $config->{debug} ||= $c->debug;
99 $config->{no_logs} = 1 unless defined $config->{no_logs};
100 $config->{no_logs} = 0 if $config->{logging};
102 # load up a MIME::Types object, only loading types with
103 # at least 1 file extension
104 $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
106 # preload the type index hash so it's not built on the first request
107 $config->{mime_types_obj}->create_type_index;
110 # Search through all included directories for the static file
111 # Based on Template Toolkit INCLUDE_PATH code
112 sub _locate_static_file {
113 my ( $c, $path, $in_static_dir ) = @_;
115 $path = File::Spec->catdir(
116 File::Spec->no_upwards( File::Spec->splitdir( $path ) )
119 my $config = $c->config->{static};
120 my @ipaths = @{ $config->{include_path} };
122 my $count = 64; # maximum number of directories to search
125 while ( @ipaths && --$count) {
126 my $dir = shift @ipaths || next DIR_CHECK;
128 if ( ref $dir eq 'CODE' ) {
129 eval { $dpaths = &$dir( $c ) };
131 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
133 unshift @ipaths, @$dpaths;
137 $dir =~ s/(\/|\\)$//xms;
138 if ( -d $dir && -f $dir . '/' . $path ) {
140 # Don't ignore any files in static dirs defined with 'dirs'
141 unless ( $in_static_dir ) {
142 # do we need to ignore the file?
143 for my $ignore ( @{ $config->{ignore_dirs} } ) {
144 $ignore =~ s{(/|\\)$}{};
145 if ( $path =~ /^$ignore(\/|\\)/ ) {
146 $c->_debug_msg( "Ignoring directory `$ignore`" )
152 # do we need to ignore based on extension?
153 for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
154 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
155 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
162 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
164 return $c->_static_file( $dir . '/' . $path );
175 my $full_path = shift || $c->_static_file;
176 my $type = $c->_ext_to_type( $full_path );
177 my $stat = stat $full_path;
179 $c->res->headers->content_type( $type );
180 $c->res->headers->content_length( $stat->size );
181 $c->res->headers->last_modified( $stat->mtime );
183 my $fh = IO::File->new( $full_path, 'r' );
186 $c->res->body( $fh );
189 Catalyst::Exception->throw(
190 message => "Unable to open $full_path for reading" );
196 sub serve_static_file {
197 my ( $c, $full_path ) = @_;
199 my $config = $c->config->{static} ||= {};
201 if ( -e $full_path ) {
202 $c->_debug_msg( "Serving static file: $full_path" )
206 $c->_debug_msg( "404: file not found: $full_path" )
208 $c->res->status( 404 );
209 $c->res->content_type( 'text/html' );
213 $c->_serve_static( $full_path );
216 # looks up the correct MIME type for the current file extension
218 my ( $c, $full_path ) = @_;
220 my $config = $c->config->{static};
222 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
224 my $type = $config->{mime_types}{$ext}
225 || $config->{mime_types_obj}->mimeTypeOf( $ext );
227 $c->_debug_msg( "as $type" ) if $config->{debug};
228 return ( ref $type ) ? $type->type : $type;
231 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
237 $c->_debug_msg( 'as text/plain (no extension)' )
244 my ( $c, $msg ) = @_;
246 if ( !defined $c->_static_debug_message ) {
247 $c->_static_debug_message( [] );
251 push @{ $c->_static_debug_message }, $msg;
254 return $c->_static_debug_message;
262 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
267 use Catalyst qw/ Static::Simple /;
269 # that's it; static content is automatically served by Catalyst
270 # from the application's root directory, though you can configure
271 # things or bypass Catalyst entirely in a production environment
273 # one caveat: the files must be served from an absolute path
274 # (i.e. /images/foo.png)
278 The Static::Simple plugin is designed to make serving static content in
279 your application during development quick and easy, without requiring a
280 single line of code from you.
282 This plugin detects static files by looking at the file extension in the
283 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
284 lightweight L<MIME::Types> module to map file extensions to
285 IANA-registered MIME types, and will serve your static files with the
286 correct MIME type directly to the browser, without being processed
289 Note that actions mapped to paths using periods (.) will still operate
292 If the plugin can not find the file, the request is dispatched to your
293 application instead. This means you are responsible for generating a
294 C<404> error if your applicaton can not process the request:
296 # handled by static::simple, not dispatched to your application
299 # static::simple will not find the file and let your application
300 # handle the request. You are responsible for generating a file
301 # or returning a 404 error
302 /images/does_not_exist.png
304 Though Static::Simple is designed to work out-of-the-box, you can tweak
305 the operation by adding various configuration options. In a production
306 environment, you will probably want to use your webserver to deliver
307 static content; for an example see L<USING WITH APACHE>, below.
309 =head1 DEFAULT BEHAVIOR
311 By default, Static::Simple will deliver all files having extensions
312 (that is, bits of text following a period (C<.>)), I<except> files
313 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
314 C<xhtml>. These files, and all files without extensions, will be
315 processed through Catalyst. If L<MIME::Types> doesn't recognize an
316 extension, it will be served as C<text/plain>.
318 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
319 and C<xhtml> I<will not> be served statically by default, they will be
320 processed by Catalyst. Thus if you want to use C<.html> files from
321 within a Catalyst app as static files, you need to change the
322 configuration of Static::Simple. Note also that files having any other
323 extension I<will> be served statically, so if you're using any other
324 extension for template files, you should also change the configuration.
326 Logging of static files is turned off by default.
328 =head1 ADVANCED CONFIGURATION
330 Configuration is completely optional and is specified within
331 C<MyApp-E<gt>config-E<gt>{static}>. If you use any of these options,
332 this module will probably feel less "simple" to you!
334 =head2 Enabling request logging
336 Since Catalyst 5.50, logging of static requests is turned off by
337 default; static requests tend to clutter the log output and rarely
338 reveal anything useful. However, if you want to enable logging of static
339 requests, you can do so by setting
340 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{logging}> to 1.
342 =head2 Forcing directories into static mode
344 Define a list of top-level directories beneath your 'root' directory
345 that should always be served in static mode. Regular expressions may be
346 specified using C<qr//>.
357 =head2 Including additional directories
359 You may specify a list of directories in which to search for your static
360 files. The directories will be searched in order and will return the
361 first file found. Note that your root directory is B<not> automatically
362 added to the search path when you specify an C<include_path>. You should
363 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
370 MyApp->config->{root},
375 With the above setting, a request for the file C</images/logo.jpg> will search
376 for the following files, returning the first one found:
378 /path/to/overlay/images/logo.jpg
379 /dynamic/path/images/logo.jpg
380 /your/app/home/root/images/logo.jpg
382 The include path can contain a subroutine reference to dynamically return a
383 list of available directories. This method will receive the C<$c> object as a
384 parameter and should return a reference to a list of directories. Errors can
385 be reported using C<die()>. This method will be called every time a file is
386 requested that appears to be a static file (i.e. it has an extension).
390 sub incpath_generator {
393 if ( $c->session->{customer_dir} ) {
394 return [ $c->session->{customer_dir} ];
396 die "No customer dir defined.";
400 =head2 Ignoring certain types of files
402 There are some file types you may not wish to serve as static files.
403 Most important in this category are your raw template files. By
404 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
405 C<xhtml> will be ignored by Static::Simple in the interest of security.
406 If you wish to define your own extensions to ignore, use the
407 C<ignore_extensions> option:
411 ignore_extensions => [ 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.
424 ignore_dirs => [ qw/tmpl css/ ],
428 For example, if combined with the above C<include_path> setting, this
429 C<ignore_dirs> value will ignore the following directories if they exist:
431 /path/to/overlay/tmpl
435 /your/app/home/root/tmpl
436 /your/app/home/root/css
438 =head2 Custom MIME types
440 To override or add to the default MIME types set by the L<MIME::Types>
441 module, you may enter your own extension to MIME type mapping.
452 =head2 Compatibility with other plugins
454 Since version 0.12, Static::Simple plays nice with other plugins. It no
455 longer short-circuits the C<prepare_action> stage as it was causing too
456 many compatibility issues with other plugins.
458 =head2 Debugging information
460 Enable additional debugging information printed in the Catalyst log. This
461 is automatically enabled when running Catalyst in -Debug mode.
469 =head1 USING WITH APACHE
471 While Static::Simple will work just fine serving files through Catalyst
472 in mod_perl, for increased performance you may wish to have Apache
473 handle the serving of your static files directly. To do this, simply use
474 a dedicated directory for your static files and configure an Apache
475 Location block for that directory This approach is recommended for
476 production installations.
478 <Location /myapp/static>
479 SetHandler default-handler
482 Using this approach Apache will bypass any handling of these directories
483 through Catalyst. You can leave Static::Simple as part of your
484 application, and it will continue to function on a development server,
485 or using Catalyst's built-in server.
487 In practice, your Catalyst application is probably (i.e. should be)
488 structured in the recommended way (i.e., that generated by bootstrapping
489 the application with the C<catalyst.pl> script, with a main directory
490 under which is a C<lib/> directory for module files and a C<root/>
491 directory for templates and static files). Thus, unless you break up
492 this structure when deploying your app by moving the static files to a
493 different location in your filesystem, you will need to use an Alias
494 directive in Apache to point to the right place. You will then need to
495 add a Directory block to give permission for Apache to serve these
496 files. The final configuration will look something like this:
498 Alias /myapp/static /filesystem/path/to/MyApp/root/static
499 <Directory /filesystem/path/to/MyApp/root/static>
502 <Location /myapp/static>
503 SetHandler default-handler
506 If you are running in a VirtualHost, you can just set the DocumentRoot
507 location to the location of your root directory; see
508 L<Catalyst::Engine::Apache2::MP20>.
510 =head1 PUBLIC METHODS
512 =head2 serve_static_file $file_path
514 Will serve the file located in $file_path statically. This is useful when
515 you need to autogenerate them if they don't exist, or they are stored in a model.
517 package MyApp::Controller::User;
519 sub curr_user_thumb : PathPart("my_thumbnail.png") {
520 my ( $self, $c ) = @_;
521 my $file_path = $c->user->picture_thumbnail_path;
522 $c->serve_static_file($file_path);
525 =head1 INTERNAL EXTENDED METHODS
527 Static::Simple extends the following steps in the Catalyst process.
529 =head2 prepare_action
531 C<prepare_action> is used to first check if the request path is a static
532 file. If so, we skip all other C<prepare_action> steps to improve
537 C<dispatch> takes the file found during C<prepare_action> and writes it
542 C<finalize> serves up final header information and displays any log
547 C<setup> initializes all default values.
551 L<Catalyst>, L<Catalyst::Plugin::Static>,
552 L<http://www.iana.org/assignments/media-types/>
556 Andy Grundman, <andy@hybridized.org>
560 Marcus Ramberg, <mramberg@cpan.org>
562 Jesse Sheidlower, <jester@panix.com>
564 Guillermo Roditi, <groditi@cpan.org>
566 Florian Ragwitz, <rafl@debian.org>
568 Tomas Doran, <bobtfish@bobtfish.net>
574 The authors of Catalyst::Plugin::Static:
580 For the include_path code from Template Toolkit:
586 Copyright (c) 2005 - 2009
587 the Catalyst::Plugin::Static::Simple L</AUTHOR> and L</CONTRIBUTORS>
592 This program is free software, you can redistribute it and/or modify it under
593 the same terms as Perl itself.