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/ );
253 # that's it; static content is automatically served by
254 # Catalyst, though you can configure things or bypass
255 # Catalyst entirely in a production environment
259 The Static::Simple plugin is designed to make serving static content in
260 your application during development quick and easy, without requiring a
261 single line of code from you.
263 This plugin detects static files by looking at the file extension in the
264 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
265 lightweight L<MIME::Types> module to map file extensions to
266 IANA-registered MIME types, and will serve your static files with the
267 correct MIME type directly to the browser, without being processed
270 Note that actions mapped to paths using periods (.) will still operate
273 Though Static::Simple is designed to work out-of-the-box, you can tweak
274 the operation by adding various configuration options. In a production
275 environment, you will probably want to use your webserver to deliver
276 static content; for an example see L<USING WITH APACHE>, below.
278 =head1 DEFAULT BEHAVIOR
280 By default, Static::Simple will deliver all files having extensions
281 (that is, bits of text following a period (C<.>)), I<except> files
282 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
283 C<xhtml>. These files, and all files without extensions, will be
284 processed through Catalyst. If L<MIME::Types> doesn't recognize an
285 extension, it will be served as C<text/plain>.
287 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
288 and C<xhtml> I<will not> be served statically by default, they will be
289 processed by Catalyst. Thus if you want to use C<.html> files from
290 within a Catalyst app as static files, you need to change the
291 configuration of Static::Simple. Note also that files having any other
292 extension I<will> be served statically, so if you're using any other
293 extension for template files, you should also change the configuration.
295 Logging of static files is turned off by default.
297 =head1 ADVANCED CONFIGURATION
299 Configuration is completely optional and is specified within
300 C<MyApp-E<gt>config-E<gt>{static}>. If you use any of these options,
301 this module will probably feel less "simple" to you!
303 =head2 Enabling request logging
305 Since Catalyst 5.50, logging of static requests is turned off by
306 default; static requests tend to clutter the log output and rarely
307 reveal anything useful. However, if you want to enable logging of static
308 requests, you can do so by setting
309 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{no_logs}> to 0.
311 =head2 Forcing directories into static mode
313 Define a list of top-level directories beneath your 'root' directory
314 that should always be served in static mode. Regular expressions may be
315 specified using C<qr//>.
317 MyApp->config->{static}->{dirs} = [
322 =head2 Including additional directories
324 You may specify a list of directories in which to search for your static
325 files. The directories will be searched in order and will return the
326 first file found. Note that your root directory is B<not> automatically
327 added to the search path when you specify an C<include_path>. You should
328 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
330 MyApp->config->{static}->{include_path} = [
333 MyApp->config->{root}
336 With the above setting, a request for the file C</images/logo.jpg> will search
337 for the following files, returning the first one found:
339 /path/to/overlay/images/logo.jpg
340 /dynamic/path/images/logo.jpg
341 /your/app/home/root/images/logo.jpg
343 The include path can contain a subroutine reference to dynamically return a
344 list of available directories. This method will receive the C<$c> object as a
345 parameter and should return a reference to a list of directories. Errors can
346 be reported using C<die()>. This method will be called every time a file is
347 requested that appears to be a static file (i.e. it has an extension).
351 sub incpath_generator {
354 if ( $c->session->{customer_dir} ) {
355 return [ $c->session->{customer_dir} ];
357 die "No customer dir defined.";
361 =head2 Ignoring certain types of files
363 There are some file types you may not wish to serve as static files.
364 Most important in this category are your raw template files. By
365 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
366 C<xhtml> will be ignored by Static::Simple in the interest of security.
367 If you wish to define your own extensions to ignore, use the
368 C<ignore_extensions> option:
370 MyApp->config->{static}->{ignore_extensions}
371 = [ qw/html asp php/ ];
373 =head2 Ignoring entire directories
375 To prevent an entire directory from being served statically, you can use
376 the C<ignore_dirs> option. This option contains a list of relative
377 directory paths to ignore. If using C<include_path>, the path will be
378 checked against every included path.
380 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
382 For example, if combined with the above C<include_path> setting, this
383 C<ignore_dirs> value will ignore the following directories if they exist:
385 /path/to/overlay/tmpl
389 /your/app/home/root/tmpl
390 /your/app/home/root/css
392 =head2 Custom MIME types
394 To override or add to the default MIME types set by the L<MIME::Types>
395 module, you may enter your own extension to MIME type mapping.
397 MyApp->config->{static}->{mime_types} = {
402 =head2 Compatibility with other plugins
404 Since version 0.12, Static::Simple plays nice with other plugins. It no
405 longer short-circuits the C<prepare_action> stage as it was causing too
406 many compatibility issues with other plugins.
408 =head2 Debugging information
410 Enable additional debugging information printed in the Catalyst log. This
411 is automatically enabled when running Catalyst in -Debug mode.
413 MyApp->config->{static}->{debug} = 1;
415 =head1 USING WITH APACHE
417 While Static::Simple will work just fine serving files through Catalyst in
418 mod_perl, for increased performance, you may wish to have Apache handle the
419 serving of your static files. To do this, simply use a dedicated directory
420 for your static files and configure an Apache Location block for that
421 directory. This approach is recommended for production installations.
424 SetHandler default-handler
427 Using this approach Apache will bypass any handling of these directories
428 through Catalyst. You can leave Static::Simple as part of your
429 application, and it will continue to function on a development server,
430 or using Catalyst's built-in server.
432 =head1 INTERNAL EXTENDED METHODS
434 Static::Simple extends the following steps in the Catalyst process.
436 =head2 prepare_action
438 C<prepare_action> is used to first check if the request path is a static
439 file. If so, we skip all other C<prepare_action> steps to improve
444 C<dispatch> takes the file found during C<prepare_action> and writes it
449 C<finalize> serves up final header information and displays any log
454 C<setup> initializes all default values.
458 L<Catalyst>, L<Catalyst::Plugin::Static>,
459 L<http://www.iana.org/assignments/media-types/>
463 Andy Grundman, <andy@hybridized.org>
467 Marcus Ramberg, <mramberg@cpan.org>
468 Jesse Sheidlower, <jester@panix.com>
472 The authors of Catalyst::Plugin::Static:
478 For the include_path code from Template Toolkit:
484 This program is free software, you can redistribute it and/or modify it under
485 the same terms as Perl itself.