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.14';
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 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
24 # is the URI in a static-defined path?
25 foreach my $dir ( @{ $c->config->{static}->{dirs} } ) {
26 my $re = ( $dir =~ /^qr\//xms ) ? eval $dir : qr/^${dir}/;
28 $c->error( "Error compiling static dir regex '$dir': $@" );
31 if ( $c->_locate_static_file( $path ) ) {
32 $c->_debug_msg( 'from static directory' )
33 if ( $c->config->{static}->{debug} );
35 $c->_debug_msg( "404: file not found: $path" )
36 if ( $c->config->{static}->{debug} );
37 $c->res->status( 404 );
42 # Does the path have an extension?
43 if ( $path =~ /.*\.(\S{1,})$/xms ) {
45 $c->_locate_static_file( $path );
48 return $c->NEXT::ACTUAL::prepare_action(@_);
54 return if ( $c->res->status != 200 );
56 if ( $c->_static_file ) {
57 if ( $c->config->{static}->{no_logs} && $c->log->can('abort') ) {
60 return $c->_serve_static;
63 return $c->NEXT::ACTUAL::dispatch(@_);
70 # display all log messages
71 if ( $c->config->{static}->{debug} && scalar @{$c->_debug_msg} ) {
72 $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
75 if ( $c->res->status =~ /^(1\d\d|[23]04)$/xms ) {
76 $c->res->headers->remove_content_headers;
77 return $c->finalize_headers;
80 return $c->NEXT::ACTUAL::finalize(@_);
88 if ( Catalyst->VERSION le '5.33' ) {
92 $c->config->{static}->{dirs} ||= [];
93 $c->config->{static}->{include_path} ||= [ $c->config->{root} ];
94 $c->config->{static}->{mime_types} ||= {};
95 $c->config->{static}->{ignore_extensions}
96 ||= [ qw/tmpl tt tt2 html xhtml/ ];
97 $c->config->{static}->{ignore_dirs} ||= [];
98 $c->config->{static}->{debug} ||= $c->debug;
99 if ( ! defined $c->config->{static}->{no_logs} ) {
100 $c->config->{static}->{no_logs} = 1;
103 # load up a MIME::Types object, only loading types with
104 # at least 1 file extension
105 $c->_static_mime_types( MIME::Types->new( only_complete => 1 ) );
107 # preload the type index hash so it's not built on the first request
108 $c->_static_mime_types->create_type_index;
111 # Search through all included directories for the static file
112 # Based on Template Toolkit INCLUDE_PATH code
113 sub _locate_static_file {
114 my ( $c, $path ) = @_;
116 $path = catdir( no_upwards( splitdir( $path ) ) );
118 my @ipaths = @{ $c->config->{static}->{include_path} };
120 my $count = 64; # maximum number of directories to search
123 while ( @ipaths && --$count) {
124 my $dir = shift @ipaths || next DIR_CHECK;
126 if ( ref $dir eq 'CODE' ) {
127 eval { $dpaths = &$dir( $c ) };
129 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
131 unshift @ipaths, @$dpaths;
135 $dir =~ s/(\/|\\)$//xms;
136 if ( -d $dir && -f $dir . '/' . $path ) {
138 # do we need to ignore the file?
139 for my $ignore ( @{ $c->config->{static}->{ignore_dirs} } ) {
140 $ignore =~ s{(/|\\)$}{};
141 if ( $path =~ /^$ignore(\/|\\)/ ) {
142 $c->_debug_msg( "Ignoring directory `$ignore`" )
143 if ( $c->config->{static}->{debug} );
148 # do we need to ignore based on extension?
150 ( @{ $c->config->{static}->{ignore_extensions} } ) {
151 if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
152 $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
153 if ( $c->config->{static}->{debug} );
158 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
159 if ( $c->config->{static}->{debug} );
160 return $c->_static_file( $dir . '/' . $path );
171 my $full_path = $c->_static_file;
172 my $type = $c->_ext_to_type( $full_path );
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
202 my ( $c, $full_path ) = @_;
204 if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
206 my $user_types = $c->config->{static}->{mime_types};
207 my $type = $user_types->{$ext}
208 || $c->_static_mime_types->mimeTypeOf( $ext );
210 $c->_debug_msg( "as $type" )
211 if ( $c->config->{static}->{debug} );
212 return ( ref $type ) ? $type->type : $type;
215 $c->_debug_msg( "as text/plain (unknown extension $ext)" )
216 if ( $c->config->{static}->{debug} );
221 $c->_debug_msg( 'as text/plain (no extension)' )
222 if ( $c->config->{static}->{debug} );
228 my ( $c, $msg ) = @_;
230 if ( !defined $c->_static_debug_message ) {
231 $c->_static_debug_message( [] );
235 push @{ $c->_static_debug_message }, $msg;
238 return $c->_static_debug_message;
246 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
251 MyApp->setup( qw/Static::Simple/ );
252 # that's it; static content is automatically served by
253 # Catalyst, though you can configure things or bypass
254 # Catalyst entirely in a production environment
258 The Static::Simple plugin is designed to make serving static content in
259 your application during development quick and easy, without requiring a
260 single line of code from you.
262 This plugin detects static files by looking at the file extension in the
263 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
264 lightweight L<MIME::Types> module to map file extensions to
265 IANA-registered MIME types, and will serve your static files with the
266 correct MIME type directly to the browser, without being processed
269 Note that actions mapped to paths using periods (.) will still operate
272 Though Static::Simple is designed to work out-of-the-box, you can tweak
273 the operation by adding various configuration options. In a production
274 environment, you will probably want to use your webserver to deliver
275 static content; for an example see L<USING WITH APACHE>, below.
277 =head1 DEFAULT BEHAVIOR
279 By default, Static::Simple will deliver all files having extensions
280 (that is, bits of text following a period (C<.>)), I<except> files
281 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
282 C<xhtml>. These files, and all files without extensions, will be
283 processed through Catalyst. If L<MIME::Types> doesn't recognize an
284 extension, it will be served as C<text/plain>.
286 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
287 and C<xhtml> I<will not> be served statically by default, they will be
288 processed by Catalyst. Thus if you want to use C<.html> files from
289 within a Catalyst app as static files, you need to change the
290 configuration of Static::Simple. Note also that files having any other
291 extension I<will> be served statically, so if you're using any other
292 extension for template files, you should also change the configuration.
294 Logging of static files is turned off by default.
296 =head1 ADVANCED CONFIGURATION
298 Configuration is completely optional and is specified within
299 C<MyApp-E<gt>config-E<gt>{static}>. If you use any of these options,
300 this module will probably feel less "simple" to you!
302 =head2 Enabling request logging
304 Since Catalyst 5.50, logging of static requests is turned off by
305 default; static requests tend to clutter the log output and rarely
306 reveal anything useful. However, if you want to enable logging of static
307 requests, you can do so by setting
308 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{no_logs}> to 0.
310 =head2 Forcing directories into static mode
312 Define a list of top-level directories beneath your 'root' directory
313 that should always be served in static mode. Regular expressions may be
314 specified using C<qr//>.
316 MyApp->config->{static}->{dirs} = [
321 =head2 Including additional directories
323 You may specify a list of directories in which to search for your static
324 files. The directories will be searched in order and will return the
325 first file found. Note that your root directory is B<not> automatically
326 added to the search path when you specify an C<include_path>. You should
327 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
329 MyApp->config->{static}->{include_path} = [
332 MyApp->config->{root}
335 With the above setting, a request for the file C</images/logo.jpg> will search
336 for the following files, returning the first one found:
338 /path/to/overlay/images/logo.jpg
339 /dynamic/path/images/logo.jpg
340 /your/app/home/root/images/logo.jpg
342 The include path can contain a subroutine reference to dynamically return a
343 list of available directories. This method will receive the C<$c> object as a
344 parameter and should return a reference to a list of directories. Errors can
345 be reported using C<die()>. This method will be called every time a file is
346 requested that appears to be a static file (i.e. it has an extension).
350 sub incpath_generator {
353 if ( $c->session->{customer_dir} ) {
354 return [ $c->session->{customer_dir} ];
356 die "No customer dir defined.";
360 =head2 Ignoring certain types of files
362 There are some file types you may not wish to serve as static files.
363 Most important in this category are your raw template files. By
364 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
365 C<xhtml> will be ignored by Static::Simple in the interest of security.
366 If you wish to define your own extensions to ignore, use the
367 C<ignore_extensions> option:
369 MyApp->config->{static}->{ignore_extensions}
370 = [ qw/html asp php/ ];
372 =head2 Ignoring entire directories
374 To prevent an entire directory from being served statically, you can use
375 the C<ignore_dirs> option. This option contains a list of relative
376 directory paths to ignore. If using C<include_path>, the path will be
377 checked against every included path.
379 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
381 For example, if combined with the above C<include_path> setting, this
382 C<ignore_dirs> value will ignore the following directories if they exist:
384 /path/to/overlay/tmpl
388 /your/app/home/root/tmpl
389 /your/app/home/root/css
391 =head2 Custom MIME types
393 To override or add to the default MIME types set by the L<MIME::Types>
394 module, you may enter your own extension to MIME type mapping.
396 MyApp->config->{static}->{mime_types} = {
401 =head2 Compatibility with other plugins
403 Since version 0.12, Static::Simple plays nice with other plugins. It no
404 longer short-circuits the C<prepare_action> stage as it was causing too
405 many compatibility issues with other plugins.
407 =head2 Debugging information
409 Enable additional debugging information printed in the Catalyst log. This
410 is automatically enabled when running Catalyst in -Debug mode.
412 MyApp->config->{static}->{debug} = 1;
414 =head1 USING WITH APACHE
416 While Static::Simple will work just fine serving files through Catalyst in
417 mod_perl, for increased performance, you may wish to have Apache handle the
418 serving of your static files. To do this, simply use a dedicated directory
419 for your static files and configure an Apache Location block for that
420 directory. This approach is recommended for production installations.
423 SetHandler default-handler
426 Using this approach Apache will bypass any handling of these directories
427 through Catalyst. You can leave Static::Simple as part of your
428 application, and it will continue to function on a development server,
429 or using Catalyst's built-in server.
431 =head1 INTERNAL EXTENDED METHODS
433 Static::Simple extends the following steps in the Catalyst process.
435 =head2 prepare_action
437 C<prepare_action> is used to first check if the request path is a static
438 file. If so, we skip all other C<prepare_action> steps to improve
443 C<dispatch> takes the file found during C<prepare_action> and writes it
448 C<finalize> serves up final header information and displays any log
453 C<setup> initializes all default values.
457 L<Catalyst>, L<Catalyst::Plugin::Static>,
458 L<http://www.iana.org/assignments/media-types/>
462 Andy Grundman, <andy@hybridized.org>
466 Marcus Ramberg, <mramberg@cpan.org>
467 Jesse Sheidlower, <jester@panix.com>
471 The authors of Catalyst::Plugin::Static:
477 For the include_path code from Template Toolkit:
483 This program is free software, you can redistribute it and/or modify it under
484 the same terms as Perl itself.