1 package Catalyst::Plugin::Static::Simple;
5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
7 use File::Spec::Functions qw/catdir no_upwards splitdir/;
12 our $VERSION = '0.13';
14 __PACKAGE__->mk_classdata( qw/_static_mime_types/ );
15 __PACKAGE__->mk_accessors( qw/_static_file
16 _static_debug_message/ );
20 my $path = $c->req->path;
22 # is the URI in a static-defined path?
23 foreach my $dir ( @{ $c->config->{static}->{dirs} } ) {
24 my $re = ( $dir =~ /^qr\//xms ) ? eval $dir : qr/^${dir}/;
26 $c->error( "Error compiling static dir regex '$dir': $@" );
29 if ( $c->_locate_static_file ) {
30 $c->_debug_msg( 'from static directory' )
31 if ( $c->config->{static}->{debug} );
33 $c->_debug_msg( "404: file not found: $path" )
34 if ( $c->config->{static}->{debug} );
35 $c->res->status( 404 );
40 # Does the path have an extension?
41 if ( $path =~ /.*\.(\S{1,})$/xms ) {
43 $c->_locate_static_file;
46 return $c->NEXT::ACTUAL::prepare_action(@_);
52 return if ( $c->res->status != 200 );
54 if ( $c->_static_file ) {
55 if ( $c->config->{static}->{no_logs} && $c->log->can('abort') ) {
58 return $c->_serve_static;
61 return $c->NEXT::ACTUAL::dispatch(@_);
68 # display all log messages
69 if ( $c->config->{static}->{debug} && scalar @{$c->_debug_msg} ) {
70 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
73 if ( $c->res->status =~ /^(1\d\d|[23]04)$/xms ) {
74 $c->res->headers->remove_content_headers;
75 return $c->finalize_headers;
78 return $c->NEXT::ACTUAL::finalize(@_);
86 if ( Catalyst->VERSION le '5.33' ) {
90 $c->config->{static}->{dirs} ||= [];
91 $c->config->{static}->{include_path} ||= [ $c->config->{root} ];
92 $c->config->{static}->{mime_types} ||= {};
93 $c->config->{static}->{ignore_extensions}
94 ||= [ qw/tmpl tt tt2 html xhtml/ ];
95 $c->config->{static}->{ignore_dirs} ||= [];
96 $c->config->{static}->{debug} ||= $c->debug;
97 if ( ! defined $c->config->{static}->{no_logs} ) {
98 $c->config->{static}->{no_logs} = 1;
101 # load up a MIME::Types object, only loading types with
102 # at least 1 file extension
103 $c->_static_mime_types( MIME::Types->new( only_complete => 1 ) );
105 # preload the type index hash so it's not built on the first request
106 $c->_static_mime_types->create_type_index;
109 # Search through all included directories for the static file
110 # Based on Template Toolkit INCLUDE_PATH code
111 sub _locate_static_file {
114 my $path = catdir( no_upwards( splitdir( $c->req->path ) ) );
116 my @ipaths = @{ $c->config->{static}->{include_path} };
118 my $count = 64; # maximum number of directories to search
121 while ( @ipaths && --$count) {
122 my $dir = shift @ipaths || next DIR_CHECK;
124 if ( ref $dir eq 'CODE' ) {
125 eval { $dpaths = &$dir( $c ) };
127 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
129 unshift @ipaths, @$dpaths;
133 $dir =~ s/(\/|\\)$//xms;
134 if ( -d $dir && -f $dir . '/' . $path ) {
136 # do we need to ignore the file?
137 for my $ignore ( @{ $c->config->{static}->{ignore_dirs} } ) {
138 $ignore =~ s{(/|\\)$}{};
139 if ( $path =~ /^$ignore(\/|\\)/ ) {
140 $c->_debug_msg( "Ignoring directory `$ignore`" )
141 if ( $c->config->{static}->{debug} );
146 # do we need to ignore based on extension?
148 ( @{ $c->config->{static}->{ignore_extensions} } ) {
149 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
150 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
151 if ( $c->config->{static}->{debug} );
156 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
157 if ( $c->config->{static}->{debug} );
158 return $c->_static_file( $dir . '/' . $path );
169 my $path = $c->req->path;
170 my $type = $c->_ext_to_type;
172 my $full_path = $c->_static_file;
173 my $stat = stat $full_path;
175 $c->res->headers->content_type( $type );
176 $c->res->headers->content_length( $stat->size );
177 $c->res->headers->last_modified( $stat->mtime );
179 if ( Catalyst->VERSION le '5.33' ) {
180 # old File::Slurp method
181 my $content = File::Slurp::read_file( $full_path );
182 $c->res->body( $content );
185 # new method, pass an IO::File object to body
186 my $fh = IO::File->new( $full_path, 'r' );
189 $c->res->body( $fh );
192 Catalyst::Exception->throw(
193 message => "Unable to open $full_path for reading" );
200 # looks up the correct MIME type for the current file extension
203 my $path = $c->req->path;
205 if ( $path =~ /.*\.(\S{1,})$/xms ) {
207 my $user_types = $c->config->{static}->{mime_types};
208 my $type = $user_types->{$ext}
209 || $c->_static_mime_types->mimeTypeOf( $ext );
211 $c->_debug_msg( "as $type" )
212 if ( $c->config->{static}->{debug} );
213 return ( ref $type ) ? $type->type : $type;
216 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
217 if ( $c->config->{static}->{debug} );
222 $c->_debug_msg( 'as text/plain (no extension)' )
223 if ( $c->config->{static}->{debug} );
229 my ( $c, $msg ) = @_;
231 if ( !defined $c->_static_debug_message ) {
232 $c->_static_debug_message( [] );
236 push @{ $c->_static_debug_message }, $msg;
239 return $c->_static_debug_message;
247 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
252 MyApp->setup( qw/Static::Simple/ );
256 The Static::Simple plugin is designed to make serving static content in your
257 application during development quick and easy, without requiring a single
258 line of code from you.
260 It will detect static files used in your application by looking for file
261 extensions in the URI. By default, you can simply load this plugin and it
262 will immediately begin serving your static files with the correct MIME type.
263 The light-weight MIME::Types module is used to map file extensions to
264 IANA-registered MIME types.
266 Note that actions mapped to paths using periods (.) will still operate
269 You may further tweak the operation by adding configuration options, described
272 =head1 ADVANCED CONFIGURATION
274 Configuration is completely optional and is specified within
275 MyApp->config->{static}. If you use any of these options, the module will
276 probably feel less "simple" to you!
278 =head2 Aborting request logging
280 Since Catalyst 5.50, there has been added support for dropping logging for a
281 request. This is enabled by default for static files, as static requests tend
282 to clutter the log output. However, if you want logging of static requests,
283 you can enable it by setting MyApp->config->{static}->{no_logs} to 0.
285 =head2 Forcing directories into static mode
287 Define a list of top-level directories beneath your 'root' directory that
288 should always be served in static mode. Regular expressions may be
289 specified using qr//.
291 MyApp->config->{static}->{dirs} = [
296 =head2 Including additional directories
298 You may specify a list of directories in which to search for your static
299 files. The directories will be searched in order and will return the first
300 file found. Note that your root directory is B<not> automatically added to
301 the search path when you specify an include_path. You should use
302 MyApp->config->{root} to add it.
304 MyApp->config->{static}->{include_path} = [
307 MyApp->config->{root}
310 With the above setting, a request for the file /images/logo.jpg will search
311 for the following files, returning the first one found:
313 /path/to/overlay/images/logo.jpg
314 /dynamic/path/images/logo.jpg
315 /your/app/home/root/images/logo.jpg
317 The include path can contain a subroutine reference to dynamically return a
318 list of available directories. This method will receive the $c object as a
319 parameter and should return a reference to a list of directories. Errors can
320 be reported using die(). This method will be called every time a file is
321 requested that appears to be a static file (i.e. it has an extension).
325 sub incpath_generator {
328 if ( $c->session->{customer_dir} ) {
329 return [ $c->session->{customer_dir} ];
331 die "No customer dir defined.";
335 =head2 Ignoring certain types of files
337 There are some file types you may not wish to serve as static files. Most
338 important in this category are your raw template files. By default, files
339 with the extensions tmpl, tt, tt2, html, and xhtml will be ignored by
340 Static::Simple in the interest of security. If you wish to define your own
341 extensions to ignore, use the ignore_extensions option:
343 MyApp->config->{static}->{ignore_extensions}
344 = [ qw/tmpl tt tt2 html xhtml/ ];
346 =head2 Ignoring entire directories
348 To prevent an entire directory from being served statically, you can use the
349 ignore_dirs option. This option contains a list of relative directory paths
350 to ignore. If using include_path, the path will be checked against every
353 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
355 For example, if combined with the above include_path setting, this
356 ignore_dirs value will ignore the following directories if they exist:
358 /path/to/overlay/tmpl
362 /your/app/home/root/tmpl
363 /your/app/home/root/css
365 =head2 Custom MIME types
367 To override or add to the default MIME types set by the MIME::Types module,
368 you may enter your own extension to MIME type mapping.
370 MyApp->config->{static}->{mime_types} = {
375 =head2 Compatibility with other plugins
377 Since version 0.12, Static::Simple plays nice with other plugins. It no
378 longer short-circuits the prepare_action stage as it was causing too many
379 compatibility issues with other plugins.
381 =head2 Debugging information
383 Enable additional debugging information printed in the Catalyst log. This
384 is automatically enabled when running Catalyst in -Debug mode.
386 MyApp->config->{static}->{debug} = 1;
388 =head1 USING WITH APACHE
390 While Static::Simple will work just fine serving files through Catalyst in
391 mod_perl, for increased performance, you may wish to have Apache handle the
392 serving of your static files. To do this, simply use a dedicated directory
393 for your static files and configure an Apache Location block for that
394 directory. This approach is recommended for production installations.
397 SetHandler default-handler
400 =head1 INTERNAL EXTENDED METHODS
402 Static::Simple extends the following steps in the Catalyst process.
404 =head2 prepare_action
406 prepare_action is used to first check if the request path is a static file.
407 If so, we skip all other prepare_action steps to improve performance.
411 dispatch takes the file found during prepare_action and writes it to the
416 finalize serves up final header information and displays any log messages.
420 setup initializes all default values.
424 L<Catalyst>, L<Catalyst::Plugin::Static>,
425 L<http://www.iana.org/assignments/media-types/>
429 Andy Grundman, <andy@hybridized.org>
433 Marcus Ramberg, <mramberg@cpan.org>
437 The authors of Catalyst::Plugin::Static:
443 For the include_path code from Template Toolkit:
449 This program is free software, you can redistribute it and/or modify it under
450 the same terms as Perl itself.