1 package Catalyst::Plugin::Static::Simple;
5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
11 our $VERSION = '0.20';
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;
26 # strip trailing slashes, they'll be added in our regex
29 my $re = ( $dir =~ m{^qr/}xms ) ? eval $dir : qr{^${dir_re}/};
31 $c->error( "Error compiling static dir regex '$dir': $@" );
34 if ( $c->_locate_static_file( $path, 1 ) ) {
35 $c->_debug_msg( 'from static directory' )
38 $c->_debug_msg( "404: file not found: $path" )
40 $c->res->status( 404 );
41 $c->res->content_type( 'text/html' );
46 # Does the path have an extension?
47 if ( $path =~ /.*\.(\S{1,})$/xms ) {
49 $c->_locate_static_file( $path );
52 return $c->NEXT::ACTUAL::prepare_action(@_);
58 return if ( $c->res->status != 200 );
60 if ( $c->_static_file ) {
61 if ( $c->config->{static}{no_logs} && $c->log->can('abort') ) {
64 return $c->_serve_static;
67 return $c->NEXT::ACTUAL::dispatch(@_);
74 # display all log messages
75 if ( $c->config->{static}{debug} && scalar @{$c->_debug_msg} ) {
76 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
79 return $c->NEXT::ACTUAL::finalize(@_);
87 if ( Catalyst->VERSION le '5.33' ) {
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 if ( Catalyst->VERSION le '5.33' ) {
184 # old File::Slurp method
185 my $content = File::Slurp::read_file( $full_path );
186 $c->res->body( $content );
189 # new method, pass an IO::File object to body
190 my $fh = IO::File->new( $full_path, 'r' );
193 $c->res->body( $fh );
196 Catalyst::Exception->throw(
197 message => "Unable to open $full_path for reading" );
204 sub serve_static_file {
205 my ( $c, $full_path ) = @_;
207 my $config = $c->config->{static} ||= {};
209 if ( -e $full_path ) {
210 $c->_debug_msg( "Serving static file: $full_path" )
214 $c->_debug_msg( "404: file not found: $full_path" )
216 $c->res->status( 404 );
217 $c->res->content_type( 'text/html' );
221 $c->_serve_static( $full_path );
224 # looks up the correct MIME type for the current file extension
226 my ( $c, $full_path ) = @_;
228 my $config = $c->config->{static};
230 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
232 my $type = $config->{mime_types}{$ext}
233 || $config->{mime_types_obj}->mimeTypeOf( $ext );
235 $c->_debug_msg( "as $type" ) if $config->{debug};
236 return ( ref $type ) ? $type->type : $type;
239 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
245 $c->_debug_msg( 'as text/plain (no extension)' )
252 my ( $c, $msg ) = @_;
254 if ( !defined $c->_static_debug_message ) {
255 $c->_static_debug_message( [] );
259 push @{ $c->_static_debug_message }, $msg;
262 return $c->_static_debug_message;
270 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
275 MyApp->setup( qw/Static::Simple/ );
276 # that's it; static content is automatically served by Catalyst
277 # from the application's root directory, though you can configure
278 # things or bypass Catalyst entirely in a production environment
280 # one caveat: the files must be served from an absolute path
281 # (i.e. /images/foo.png)
285 The Static::Simple plugin is designed to make serving static content in
286 your application during development quick and easy, without requiring a
287 single line of code from you.
289 This plugin detects static files by looking at the file extension in the
290 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
291 lightweight L<MIME::Types> module to map file extensions to
292 IANA-registered MIME types, and will serve your static files with the
293 correct MIME type directly to the browser, without being processed
296 Note that actions mapped to paths using periods (.) will still operate
299 Though Static::Simple is designed to work out-of-the-box, you can tweak
300 the operation by adding various configuration options. In a production
301 environment, you will probably want to use your webserver to deliver
302 static content; for an example see L<USING WITH APACHE>, below.
304 =head1 DEFAULT BEHAVIOR
306 By default, Static::Simple will deliver all files having extensions
307 (that is, bits of text following a period (C<.>)), I<except> files
308 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
309 C<xhtml>. These files, and all files without extensions, will be
310 processed through Catalyst. If L<MIME::Types> doesn't recognize an
311 extension, it will be served as C<text/plain>.
313 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
314 and C<xhtml> I<will not> be served statically by default, they will be
315 processed by Catalyst. Thus if you want to use C<.html> files from
316 within a Catalyst app as static files, you need to change the
317 configuration of Static::Simple. Note also that files having any other
318 extension I<will> be served statically, so if you're using any other
319 extension for template files, you should also change the configuration.
321 Logging of static files is turned off by default.
323 =head1 ADVANCED CONFIGURATION
325 Configuration is completely optional and is specified within
326 C<MyApp-E<gt>config-E<gt>{static}>. If you use any of these options,
327 this module will probably feel less "simple" to you!
329 =head2 Enabling request logging
331 Since Catalyst 5.50, logging of static requests is turned off by
332 default; static requests tend to clutter the log output and rarely
333 reveal anything useful. However, if you want to enable logging of static
334 requests, you can do so by setting
335 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{logging}> to 1.
337 =head2 Forcing directories into static mode
339 Define a list of top-level directories beneath your 'root' directory
340 that should always be served in static mode. Regular expressions may be
341 specified using C<qr//>.
343 MyApp->config->{static}->{dirs} = [
348 =head2 Including additional directories
350 You may specify a list of directories in which to search for your static
351 files. The directories will be searched in order and will return the
352 first file found. Note that your root directory is B<not> automatically
353 added to the search path when you specify an C<include_path>. You should
354 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
356 MyApp->config->{static}->{include_path} = [
359 MyApp->config->{root}
362 With the above setting, a request for the file C</images/logo.jpg> will search
363 for the following files, returning the first one found:
365 /path/to/overlay/images/logo.jpg
366 /dynamic/path/images/logo.jpg
367 /your/app/home/root/images/logo.jpg
369 The include path can contain a subroutine reference to dynamically return a
370 list of available directories. This method will receive the C<$c> object as a
371 parameter and should return a reference to a list of directories. Errors can
372 be reported using C<die()>. This method will be called every time a file is
373 requested that appears to be a static file (i.e. it has an extension).
377 sub incpath_generator {
380 if ( $c->session->{customer_dir} ) {
381 return [ $c->session->{customer_dir} ];
383 die "No customer dir defined.";
387 =head2 Ignoring certain types of files
389 There are some file types you may not wish to serve as static files.
390 Most important in this category are your raw template files. By
391 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
392 C<xhtml> will be ignored by Static::Simple in the interest of security.
393 If you wish to define your own extensions to ignore, use the
394 C<ignore_extensions> option:
396 MyApp->config->{static}->{ignore_extensions}
397 = [ qw/html asp php/ ];
399 =head2 Ignoring entire directories
401 To prevent an entire directory from being served statically, you can use
402 the C<ignore_dirs> option. This option contains a list of relative
403 directory paths to ignore. If using C<include_path>, the path will be
404 checked against every included path.
406 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
408 For example, if combined with the above C<include_path> setting, this
409 C<ignore_dirs> value will ignore the following directories if they exist:
411 /path/to/overlay/tmpl
415 /your/app/home/root/tmpl
416 /your/app/home/root/css
418 =head2 Custom MIME types
420 To override or add to the default MIME types set by the L<MIME::Types>
421 module, you may enter your own extension to MIME type mapping.
423 MyApp->config->{static}->{mime_types} = {
428 =head2 Compatibility with other plugins
430 Since version 0.12, Static::Simple plays nice with other plugins. It no
431 longer short-circuits the C<prepare_action> stage as it was causing too
432 many compatibility issues with other plugins.
434 =head2 Debugging information
436 Enable additional debugging information printed in the Catalyst log. This
437 is automatically enabled when running Catalyst in -Debug mode.
439 MyApp->config->{static}->{debug} = 1;
441 =head1 USING WITH APACHE
443 While Static::Simple will work just fine serving files through Catalyst
444 in mod_perl, for increased performance you may wish to have Apache
445 handle the serving of your static files directly. To do this, simply use
446 a dedicated directory for your static files and configure an Apache
447 Location block for that directory This approach is recommended for
448 production installations.
450 <Location /myapp/static>
451 SetHandler default-handler
454 Using this approach Apache will bypass any handling of these directories
455 through Catalyst. You can leave Static::Simple as part of your
456 application, and it will continue to function on a development server,
457 or using Catalyst's built-in server.
459 In practice, your Catalyst application is probably (i.e. should be)
460 structured in the recommended way (i.e., that generated by bootstrapping
461 the application with the C<catalyst.pl> script, with a main directory
462 under which is a C<lib/> directory for module files and a C<root/>
463 directory for templates and static files). Thus, unless you break up
464 this structure when deploying your app by moving the static files to a
465 different location in your filesystem, you will need to use an Alias
466 directive in Apache to point to the right place. You will then need to
467 add a Directory block to give permission for Apache to serve these
468 files. The final configuration will look something like this:
470 Alias /myapp/static /filesystem/path/to/MyApp/root/static
471 <Directory /filesystem/path/to/MyApp/root/static>
474 <Location /myapp/static>
475 SetHandler default-handler
478 =head1 PUBLIC METHODS
480 =head2 serve_static_file $file_path
482 Will serve the file located in $file_path statically. This is useful when
483 you need to autogenerate them if they don't exist, or they are stored in a model.
485 package MyApp::Controller::User;
487 sub curr_user_thumb : PathPart("my_thumbnail.png") {
488 my ( $self, $c ) = @_;
489 my $file_path = $c->user->picture_thumbnail_path;
490 $c->serve_static_file($file_path);
493 =head1 INTERNAL EXTENDED METHODS
495 Static::Simple extends the following steps in the Catalyst process.
497 =head2 prepare_action
499 C<prepare_action> is used to first check if the request path is a static
500 file. If so, we skip all other C<prepare_action> steps to improve
505 C<dispatch> takes the file found during C<prepare_action> and writes it
510 C<finalize> serves up final header information and displays any log
515 C<setup> initializes all default values.
519 L<Catalyst>, L<Catalyst::Plugin::Static>,
520 L<http://www.iana.org/assignments/media-types/>
524 Andy Grundman, <andy@hybridized.org>
528 Marcus Ramberg, <mramberg@cpan.org>
530 Jesse Sheidlower, <jester@panix.com>
532 Guillermo Roditi, <groditi@cpan.org>
536 The authors of Catalyst::Plugin::Static:
542 For the include_path code from Template Toolkit:
548 This program is free software, you can redistribute it and/or modify it under
549 the same terms as Perl itself.