lib/Catalyst/Plugin/Static/Simple.pm

   1 package Catalyst::Plugin::Static::Simple;
   2
   3 use strict;
   4 use warnings;
   5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
   6 use File::stat;
   7 use File::Spec ();
   8 use IO::File ();
   9 use MIME::Types ();
  10
  11 our $VERSION = '0.18';
  12
  13 __PACKAGE__->mk_accessors( qw/_static_file _static_debug_message/ );
  14
  15 sub prepare_action {
  16     my $c = shift;
  17     my $path = $c->req->path;
  18     my $config = $c->config->{static};
  19
  20     $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
  21
  22     # is the URI in a static-defined path?
  23     foreach my $dir ( @{ $config->{dirs} } ) {
  24         my $dir_re = quotemeta $dir;
  25         my $re = ( $dir =~ m{^qr/}xms ) ? eval $dir : qr/^${dir_re}/;
  26         if ($@) {
  27             $c->error( "Error compiling static dir regex '$dir': $@" );
  28         }
  29         if ( $path =~ $re ) {
  30             if ( $c->_locate_static_file( $path, 1 ) ) {
  31                 $c->_debug_msg( 'from static directory' )
  32                     if $config->{debug};
  33             } else {
  34                 $c->_debug_msg( "404: file not found: $path" )
  35                     if $config->{debug};
  36                 $c->res->status( 404 );
  37             }
  38         }
  39     }
  40
  41     # Does the path have an extension?
  42     if ( $path =~ /.*\.(\S{1,})$/xms ) {
  43         # and does it exist?
  44         $c->_locate_static_file( $path );
  45     }
  46
  47     return $c->NEXT::ACTUAL::prepare_action(@_);
  48 }
  49
  50 sub dispatch {
  51     my $c = shift;
  52
  53     return if ( $c->res->status != 200 );
  54
  55     if ( $c->_static_file ) {
  56         if ( $c->config->{static}{no_logs} && $c->log->can('abort') ) {
  57            $c->log->abort( 1 );
  58         }
  59         return $c->_serve_static;
  60     }
  61     else {
  62         return $c->NEXT::ACTUAL::dispatch(@_);
  63     }
  64 }
  65
  66 sub finalize {
  67     my $c = shift;
  68
  69     # display all log messages
  70     if ( $c->config->{static}{debug} && scalar @{$c->_debug_msg} ) {
  71         $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
  72     }
  73
  74     return $c->NEXT::ACTUAL::finalize(@_);
  75 }
  76
  77 sub setup {
  78     my $c = shift;
  79
  80     $c->NEXT::setup(@_);
  81
  82     if ( Catalyst->VERSION le '5.33' ) {
  83         require File::Slurp;
  84     }
  85
  86     my $config = $c->config->{static} ||= {};
  87
  88     $config->{dirs} ||= [];
  89     $config->{include_path} ||= [ $c->config->{root} ];
  90     $config->{mime_types} ||= {};
  91     $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
  92     $config->{ignore_dirs} ||= [];
  93     $config->{debug} ||= $c->debug;
  94     $config->{no_logs} = 1 unless defined $config->{no_logs};
  95     $config->{no_logs} = 0 if $config->{logging};
  96
  97     # load up a MIME::Types object, only loading types with
  98     # at least 1 file extension
  99     $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
 100
 101     # preload the type index hash so it's not built on the first request
 102     $config->{mime_types_obj}->create_type_index;
 103 }
 104
 105 # Search through all included directories for the static file
 106 # Based on Template Toolkit INCLUDE_PATH code
 107 sub _locate_static_file {
 108     my ( $c, $path, $in_static_dir ) = @_;
 109
 110     $path = File::Spec->catdir(
 111         File::Spec->no_upwards( File::Spec->splitdir( $path ) )
 112     );
 113
 114     my $config = $c->config->{static};
 115     my @ipaths = @{ $config->{include_path} };
 116     my $dpaths;
 117     my $count = 64; # maximum number of directories to search
 118
 119     DIR_CHECK:
 120     while ( @ipaths && --$count) {
 121         my $dir = shift @ipaths || next DIR_CHECK;
 122
 123         if ( ref $dir eq 'CODE' ) {
 124             eval { $dpaths = &$dir( $c ) };
 125             if ($@) {
 126                 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
 127             } else {
 128                 unshift @ipaths, @$dpaths;
 129                 next DIR_CHECK;
 130             }
 131         } else {
 132             $dir =~ s/(\/|\\)$//xms;
 133             if ( -d $dir && -f $dir . '/' . $path ) {
 134
 135                 # Don't ignore any files in static dirs defined with 'dirs'
 136                 unless ( $in_static_dir ) {
 137                     # do we need to ignore the file?
 138                     for my $ignore ( @{ $config->{ignore_dirs} } ) {
 139                         $ignore =~ s{(/|\\)$}{};
 140                         if ( $path =~ /^$ignore(\/|\\)/ ) {
 141                             $c->_debug_msg( "Ignoring directory `$ignore`" )
 142                                 if $config->{debug};
 143                             next DIR_CHECK;
 144                         }
 145                     }
 146
 147                     # do we need to ignore based on extension?
 148                     for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
 149                         if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
 150                             $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
 151                                 if $config->{debug};
 152                             next DIR_CHECK;
 153                         }
 154                     }
 155                 }
 156
 157                 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
 158                     if $config->{debug};
 159                 return $c->_static_file( $dir . '/' . $path );
 160             }
 161         }
 162     }
 163
 164     return;
 165 }
 166
 167 sub _serve_static {
 168     my $c = shift;
 169
 170     my $full_path = shift || $c->_static_file;
 171     my $type      = $c->_ext_to_type( $full_path );
 172     my $stat      = stat $full_path;
 173
 174     $c->res->headers->content_type( $type );
 175     $c->res->headers->content_length( $stat->size );
 176     $c->res->headers->last_modified( $stat->mtime );
 177
 178     if ( Catalyst->VERSION le '5.33' ) {
 179         # old File::Slurp method
 180         my $content = File::Slurp::read_file( $full_path );
 181         $c->res->body( $content );
 182     }
 183     else {
 184         # new method, pass an IO::File object to body
 185         my $fh = IO::File->new( $full_path, 'r' );
 186         if ( defined $fh ) {
 187             binmode $fh;
 188             $c->res->body( $fh );
 189         }
 190         else {
 191             Catalyst::Exception->throw(
 192                 message => "Unable to open $full_path for reading" );
 193         }
 194     }
 195
 196     return 1;
 197 }
 198
 199 sub serve_static_file {
 200     my ( $c, $full_path ) = @_;
 201
 202     my $config = $c->config->{static} ||= {};
 203
 204     if ( -e $full_path ) {
 205         $c->_debug_msg( "Serving static file: $full_path" )
 206             if $config->{debug};
 207     }
 208     else {
 209         $c->_debug_msg( "404: file not found: $full_path" )
 210             if $config->{debug};
 211         $c->res->status( 404 );
 212         return;
 213     }
 214
 215     $c->_serve_static( $full_path );
 216 }
 217
 218 # looks up the correct MIME type for the current file extension
 219 sub _ext_to_type {
 220     my ( $c, $full_path ) = @_;
 221
 222     my $config = $c->config->{static};
 223
 224     if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
 225         my $ext = $1;
 226         my $type = $config->{mime_types}{$ext}
 227             || $config->{mime_types_obj}->mimeTypeOf( $ext );
 228         if ( $type ) {
 229             $c->_debug_msg( "as $type" ) if $config->{debug};
 230             return ( ref $type ) ? $type->type : $type;
 231         }
 232         else {
 233             $c->_debug_msg( "as text/plain (unknown extension $ext)" )
 234                 if $config->{debug};
 235             return 'text/plain';
 236         }
 237     }
 238     else {
 239         $c->_debug_msg( 'as text/plain (no extension)' )
 240             if $config->{debug};
 241         return 'text/plain';
 242     }
 243 }
 244
 245 sub _debug_msg {
 246     my ( $c, $msg ) = @_;
 247
 248     if ( !defined $c->_static_debug_message ) {
 249         $c->_static_debug_message( [] );
 250     }
 251
 252     if ( $msg ) {
 253         push @{ $c->_static_debug_message }, $msg;
 254     }
 255
 256     return $c->_static_debug_message;
 257 }
 258
 259 1;
 260 __END__
 261
 262 =head1 NAME
 263
 264 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
 265
 266 =head1 SYNOPSIS
 267
 268     use Catalyst;
 269     MyApp->setup( qw/Static::Simple/ );
 270     # that's it; static content is automatically served by
 271     # Catalyst, though you can configure things or bypass
 272     # Catalyst entirely in a production environment
 273
 274 =head1 DESCRIPTION
 275
 276 The Static::Simple plugin is designed to make serving static content in
 277 your application during development quick and easy, without requiring a
 278 single line of code from you.
 279
 280 This plugin detects static files by looking at the file extension in the
 281 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
 282 lightweight L<MIME::Types> module to map file extensions to
 283 IANA-registered MIME types, and will serve your static files with the
 284 correct MIME type directly to the browser, without being processed
 285 through Catalyst.
 286
 287 Note that actions mapped to paths using periods (.) will still operate
 288 properly.
 289
 290 Though Static::Simple is designed to work out-of-the-box, you can tweak
 291 the operation by adding various configuration options. In a production
 292 environment, you will probably want to use your webserver to deliver
 293 static content; for an example see L<USING WITH APACHE>, below.
 294
 295 =head1 DEFAULT BEHAVIOR
 296
 297 By default, Static::Simple will deliver all files having extensions
 298 (that is, bits of text following a period (C<.>)), I<except> files
 299 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
 300 C<xhtml>. These files, and all files without extensions, will be
 301 processed through Catalyst. If L<MIME::Types> doesn't recognize an
 302 extension, it will be served as C<text/plain>.
 303
 304 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
 305 and C<xhtml> I<will not> be served statically by default, they will be
 306 processed by Catalyst. Thus if you want to use C<.html> files from
 307 within a Catalyst app as static files, you need to change the
 308 configuration of Static::Simple. Note also that files having any other
 309 extension I<will> be served statically, so if you're using any other
 310 extension for template files, you should also change the configuration.
 311
 312 Logging of static files is turned off by default.
 313
 314 =head1 ADVANCED CONFIGURATION
 315
 316 Configuration is completely optional and is specified within
 317 C<MyApp-E<gt>config-E<gt>{static}>.  If you use any of these options,
 318 this module will probably feel less "simple" to you!
 319
 320 =head2 Enabling request logging
 321
 322 Since Catalyst 5.50, logging of static requests is turned off by
 323 default; static requests tend to clutter the log output and rarely
 324 reveal anything useful. However, if you want to enable logging of static
 325 requests, you can do so by setting
 326 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{logging}> to 1.
 327
 328 =head2 Forcing directories into static mode
 329
 330 Define a list of top-level directories beneath your 'root' directory
 331 that should always be served in static mode.  Regular expressions may be
 332 specified using C<qr//>.
 333
 334     MyApp->config->{static}->{dirs} = [
 335         'static',
 336         qr/^(images|css)/,
 337     ];
 338
 339 =head2 Including additional directories
 340
 341 You may specify a list of directories in which to search for your static
 342 files. The directories will be searched in order and will return the
 343 first file found. Note that your root directory is B<not> automatically
 344 added to the search path when you specify an C<include_path>. You should
 345 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
 346
 347     MyApp->config->{static}->{include_path} = [
 348         '/path/to/overlay',
 349         \&incpath_generator,
 350         MyApp->config->{root}
 351     ];
 352
 353 With the above setting, a request for the file C</images/logo.jpg> will search
 354 for the following files, returning the first one found:
 355
 356     /path/to/overlay/images/logo.jpg
 357     /dynamic/path/images/logo.jpg
 358     /your/app/home/root/images/logo.jpg
 359
 360 The include path can contain a subroutine reference to dynamically return a
 361 list of available directories.  This method will receive the C<$c> object as a
 362 parameter and should return a reference to a list of directories.  Errors can
 363 be reported using C<die()>.  This method will be called every time a file is
 364 requested that appears to be a static file (i.e. it has an extension).
 365
 366 For example:
 367
 368     sub incpath_generator {
 369         my $c = shift;
 370
 371         if ( $c->session->{customer_dir} ) {
 372             return [ $c->session->{customer_dir} ];
 373         } else {
 374             die "No customer dir defined.";
 375         }
 376     }
 377
 378 =head2 Ignoring certain types of files
 379
 380 There are some file types you may not wish to serve as static files.
 381 Most important in this category are your raw template files.  By
 382 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
 383 C<xhtml> will be ignored by Static::Simple in the interest of security.
 384 If you wish to define your own extensions to ignore, use the
 385 C<ignore_extensions> option:
 386
 387     MyApp->config->{static}->{ignore_extensions}
 388         = [ qw/html asp php/ ];
 389
 390 =head2 Ignoring entire directories
 391
 392 To prevent an entire directory from being served statically, you can use
 393 the C<ignore_dirs> option.  This option contains a list of relative
 394 directory paths to ignore.  If using C<include_path>, the path will be
 395 checked against every included path.
 396
 397     MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
 398
 399 For example, if combined with the above C<include_path> setting, this
 400 C<ignore_dirs> value will ignore the following directories if they exist:
 401
 402     /path/to/overlay/tmpl
 403     /path/to/overlay/css
 404     /dynamic/path/tmpl
 405     /dynamic/path/css
 406     /your/app/home/root/tmpl
 407     /your/app/home/root/css
 408
 409 =head2 Custom MIME types
 410
 411 To override or add to the default MIME types set by the L<MIME::Types>
 412 module, you may enter your own extension to MIME type mapping.
 413
 414     MyApp->config->{static}->{mime_types} = {
 415         jpg => 'image/jpg',
 416         png => 'image/png',
 417     };
 418
 419 =head2 Compatibility with other plugins
 420
 421 Since version 0.12, Static::Simple plays nice with other plugins.  It no
 422 longer short-circuits the C<prepare_action> stage as it was causing too
 423 many compatibility issues with other plugins.
 424
 425 =head2 Debugging information
 426
 427 Enable additional debugging information printed in the Catalyst log.  This
 428 is automatically enabled when running Catalyst in -Debug mode.
 429
 430     MyApp->config->{static}->{debug} = 1;
 431
 432 =head1 USING WITH APACHE
 433
 434 While Static::Simple will work just fine serving files through Catalyst in
 435 mod_perl, for increased performance, you may wish to have Apache handle the
 436 serving of your static files.  To do this, simply use a dedicated directory
 437 for your static files and configure an Apache Location block for that
 438 directory.  This approach is recommended for production installations.
 439
 440     <Location /static>
 441         SetHandler default-handler
 442     </Location>
 443
 444 Using this approach Apache will bypass any handling of these directories
 445 through Catalyst. You can leave Static::Simple as part of your
 446 application, and it will continue to function on a development server,
 447 or using Catalyst's built-in server.
 448
 449 =head1 PUBLIC METHODS
 450
 451 =head2 serve_static_file $file_path
 452
 453 Will serve the file located in $file_path statically. This is useful when
 454 you need to  autogenerate them if they don't exist, or they are stored in a model.
 455
 456     package MyApp::Controller::User;
 457
 458     sub curr_user_thumb : PathPart("my_thumbnail.png") {
 459         my ( $self, $c ) = @_;
 460         my $file_path = $c->user->picture_thumbnail_path;
 461         $c->serve_static_file($file_path);
 462     }
 463
 464 =head1 INTERNAL EXTENDED METHODS
 465
 466 Static::Simple extends the following steps in the Catalyst process.
 467
 468 =head2 prepare_action
 469
 470 C<prepare_action> is used to first check if the request path is a static
 471 file.  If so, we skip all other C<prepare_action> steps to improve
 472 performance.
 473
 474 =head2 dispatch
 475
 476 C<dispatch> takes the file found during C<prepare_action> and writes it
 477 to the output.
 478
 479 =head2 finalize
 480
 481 C<finalize> serves up final header information and displays any log
 482 messages.
 483
 484 =head2 setup
 485
 486 C<setup> initializes all default values.
 487
 488 =head1 SEE ALSO
 489
 490 L<Catalyst>, L<Catalyst::Plugin::Static>,
 491 L<http://www.iana.org/assignments/media-types/>
 492
 493 =head1 AUTHOR
 494
 495 Andy Grundman, <andy@hybridized.org>
 496
 497 =head1 CONTRIBUTORS
 498
 499 Marcus Ramberg, <mramberg@cpan.org>
 500
 501 Jesse Sheidlower, <jester@panix.com>
 502
 503 Guillermo Roditi, <groditi@cpan.org>
 504
 505 =head1 THANKS
 506
 507 The authors of Catalyst::Plugin::Static:
 508
 509     Sebastian Riedel
 510     Christian Hansen
 511     Marcus Ramberg
 512
 513 For the include_path code from Template Toolkit:
 514
 515     Andy Wardley
 516
 517 =head1 COPYRIGHT
 518
 519 This program is free software, you can redistribute it and/or modify it under
 520 the same terms as Perl itself.
 521
 522 =cut