1 package Catalyst::Plugin::Static::Simple;
5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
11 if ( Catalyst->VERSION le '5.33' ) {
15 our $VERSION = '0.11';
17 __PACKAGE__->mk_classdata( qw/_static_mime_types/ );
18 __PACKAGE__->mk_accessors( qw/_static_file
19 _static_debug_message/ );
21 # prepare_action is used to first check if the request path is a static file.
22 # If so, we skip all other prepare_action steps to improve performance.
25 my $path = $c->req->path;
27 # is the URI in a static-defined path?
28 foreach my $dir ( @{ $c->config->{static}->{dirs} } ) {
29 my $re = ( $dir =~ /^qr\//xms ) ? eval $dir : qr/^${dir}/;
31 $c->error( "Error compiling static dir regex '$dir': $@" );
34 if ( $c->_locate_static_file ) {
35 $c->_debug_msg( 'from static directory' )
36 if ( $c->config->{static}->{debug} );
39 $c->_debug_msg( "404: file not found: $path" )
40 if ( $c->config->{static}->{debug} );
41 $c->res->status( 404 );
47 # Does the path have an extension?
48 if ( $path =~ /.*\.(\S{1,})$/xms ) {
50 return if ( $c->_locate_static_file );
53 return $c->NEXT::ACTUAL::prepare_action(@_);
56 # dispatch takes the file found during prepare_action and serves it
60 return if ( $c->res->status != 200 );
62 if ( $c->_static_file ) {
63 if ( $c->config->{static}->{no_logs} && $c->log->can('abort') ) {
66 return $c->_serve_static;
69 return $c->NEXT::ACTUAL::dispatch(@_);
73 # finalize serves up final header information
77 # display all log messages
78 if ( $c->config->{static}->{debug} && scalar @{$c->_debug_msg} ) {
79 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
82 if ( $c->res->status =~ /^(1\d\d|[23]04)$/xms ) {
83 $c->res->headers->remove_content_headers;
84 return $c->finalize_headers;
87 return $c->NEXT::ACTUAL::finalize(@_);
95 $c->config->{static}->{dirs} ||= [];
96 $c->config->{static}->{include_path} ||= [ $c->config->{root} ];
97 $c->config->{static}->{mime_types} ||= {};
98 $c->config->{static}->{ignore_extensions} ||= [ qw/tt tt2 html xhtml/ ];
99 $c->config->{static}->{ignore_dirs} ||= [];
100 $c->config->{static}->{debug} ||= $c->debug;
101 if ( ! defined $c->config->{static}->{no_logs} ) {
102 $c->config->{static}->{no_logs} = 1;
105 # load up a MIME::Types object, only loading types with
106 # at least 1 file extension
107 $c->_static_mime_types( MIME::Types->new( only_complete => 1 ) );
109 # preload the type index hash so it's not built on the first request
110 $c->_static_mime_types->create_type_index;
113 # Search through all included directories for the static file
114 # Based on Template Toolkit INCLUDE_PATH code
115 sub _locate_static_file {
118 my $path = $c->req->path;
120 my @ipaths = @{ $c->config->{static}->{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;
138 if ( -d $dir && -f $dir . '/' . $path ) {
140 # do we need to ignore the file?
141 for my $ignore ( @{ $c->config->{static}->{ignore_dirs} } ) {
143 if ( $path =~ /^$ignore\// ) {
144 $c->_debug_msg( "Ignoring directory `$ignore`" )
145 if ( $c->config->{static}->{debug} );
150 # do we need to ignore based on extension?
152 ( @{ $c->config->{static}->{ignore_extensions} } ) {
153 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
154 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
155 if ( $c->config->{static}->{debug} );
160 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
161 if ( $c->config->{static}->{debug} );
162 return $c->_static_file( $dir . '/' . $path );
173 my $path = $c->req->path;
174 my $type = $c->_ext_to_type;
176 my $full_path = $c->_static_file;
177 my $stat = stat $full_path;
179 # the below code all from C::P::Static
180 if ( $c->req->headers->if_modified_since ) {
181 if ( $c->req->headers->if_modified_since == $stat->mtime ) {
182 $c->res->status( 304 ); # Not Modified
183 $c->res->headers->remove_content_headers;
188 $c->res->headers->content_type( $type );
189 $c->res->headers->content_length( $stat->size );
190 $c->res->headers->last_modified( $stat->mtime );
192 if ( Catalyst->VERSION le '5.33' ) {
193 # old File::Slurp method
194 my $content = File::Slurp::read_file( $full_path );
195 $c->res->body( $content );
198 # new method, pass an IO::File object to body
199 my $fh = IO::File->new( $full_path, 'r' );
201 $c->res->body( $fh );
204 Catalyst::Exception->throw(
205 message => "Unable to open $full_path for reading" );
212 # looks up the correct MIME type for the current file extension
215 my $path = $c->req->path;
217 if ( $path =~ /.*\.(\S{1,})$/xms ) {
219 my $user_types = $c->config->{static}->{mime_types};
220 my $type = $user_types->{$ext}
221 || $c->_static_mime_types->mimeTypeOf( $ext );
223 $c->_debug_msg( "as $type" )
224 if ( $c->config->{static}->{debug} );
225 return ( ref $type ) ? $type->type : $type;
228 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
229 if ( $c->config->{static}->{debug} );
234 $c->_debug_msg( 'as text/plain (no extension)' )
235 if ( $c->config->{static}->{debug} );
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 MyApp->setup( qw/Static::Simple/ );
268 The Static::Simple plugin is designed to make serving static content in your
269 application during development quick and easy, without requiring a single
270 line of code from you.
272 It will detect static files used in your application by looking for file
273 extensions in the URI. By default, you can simply load this plugin and it
274 will immediately begin serving your static files with the correct MIME type.
275 The light-weight MIME::Types module is used to map file extensions to
276 IANA-registered MIME types.
278 Note that actions mapped to paths using periods (.) will still operate
281 You may further tweak the operation by adding configuration options, described
284 =head1 ADVANCED CONFIGURATION
286 Configuration is completely optional and is specified within
287 MyApp->config->{static}. If you use any of these options, the module will
288 probably feel less "simple" to you!
290 =head2 Aborting request logging
292 Since Catalyst 5.50, there has been added support for dropping logging for a
293 request. This is enabled by default for static files, as static requests tend
294 to clutter the log output. However, if you want logging of static requests,
295 you can enable it by setting MyApp->config->{static}->{no_logs} to 0.
297 =head2 Forcing directories into static mode
299 Define a list of top-level directories beneath your 'root' directory that
300 should always be served in static mode. Regular expressions may be
301 specified using qr//.
303 MyApp->config->{static}->{dirs} = [
308 =head2 Including additional directories
310 You may specify a list of directories in which to search for your static
311 files. The directories will be searched in order and will return the first
312 file found. Note that your root directory is B<not> automatically added to
313 the search path when you specify an include_path. You should use
314 MyApp->config->{root} to add it.
316 MyApp->config->{static}->{include_path} = [
319 MyApp->config->{root}
322 With the above setting, a request for the file /images/logo.jpg will search
323 for the following files, returning the first one found:
325 /path/to/overlay/images/logo.jpg
326 /dynamic/path/images/logo.jpg
327 /your/app/home/root/images/logo.jpg
329 The include path can contain a subroutine reference to dynamically return a
330 list of available directories. This method will receive the $c object as a
331 parameter and should return a reference to a list of directories. Errors can
332 be reported using die(). This method will be called every time a file is
333 requested that appears to be a static file (i.e. it has an extension).
337 sub incpath_generator {
340 if ( $c->session->{customer_dir} ) {
341 return [ $c->session->{customer_dir} ];
343 die "No customer dir defined.";
347 =head2 Ignoring certain types of files
349 There are some file types you may not wish to serve as static files. Most
350 important in this category are your raw template files. By default, files
351 with the extensions tt, tt2, html, and xhtml will be ignored by Static::Simple
352 in the interest of security. If you wish to define your own extensions to
353 ignore, use the ignore_extensions option:
355 MyApp->config->{static}->{ignore_extensions} = [ qw/tt tt2 html xhtml/ ];
357 =head2 Ignoring entire directories
359 To prevent an entire directory from being served statically, you can use the
360 ignore_dirs option. This option contains a list of relative directory paths
361 to ignore. If using include_path, the path will be checked against every
364 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
366 For example, if combined with the above include_path setting, this
367 ignore_dirs value will ignore the following directories if they exist:
369 /path/to/overlay/tmpl
373 /your/app/home/root/tmpl
374 /your/app/home/root/css
376 =head2 Custom MIME types
378 To override or add to the default MIME types set by the MIME::Types module,
379 you may enter your own extension to MIME type mapping.
381 MyApp->config->{static}->{mime_types} = {
386 =head2 Bypassing other plugins
388 This plugin checks for a static file in the prepare_action stage. If the
389 request is for a static file, it will bypass all remaining prepare_action
390 steps. This means that by placing Static::Simple before all other plugins,
391 they will not execute when a static file is found. This can be helpful by
392 skipping session cookie checks for example. Or, if you want some plugins
393 to run even on static files, list them before Static::Simple.
395 Currently, work done by plugins in any other prepare method will execute
398 =head2 Debugging information
400 Enable additional debugging information printed in the Catalyst log. This
401 is automatically enabled when running Catalyst in -Debug mode.
403 MyApp->config->{static}->{debug} = 1;
405 =head1 USING WITH APACHE
407 While Static::Simple will work just fine serving files through Catalyst in
408 mod_perl, for increased performance, you may wish to have Apache handle the
409 serving of your static files. To do this, simply use a dedicated directory
410 for your static files and configure an Apache Location block for that
411 directory. This approach is recommended for production installations.
414 SetHandler default-handler
419 L<Catalyst>, L<Catalyst::Plugin::Static>,
420 L<http://www.iana.org/assignments/media-types/>
424 Andy Grundman, <andy@hybridized.org>
428 Marcus Ramberg, <mramberg@cpan.org>
432 The authors of Catalyst::Plugin::Static:
438 For the include_path code from Template Toolkit:
444 This program is free software, you can redistribute it and/or modify it under
445 the same terms as Perl itself.