2 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
6 MyApp->setup( qw/Static::Simple/ );
9 The Static::Simple plugin is designed to make serving static content in
10 your application during development quick and easy, without requiring a
11 single line of code from you.
13 It will detect static files used in your application by looking for file
14 extensions in the URI. By default, you can simply load this plugin and
15 it will immediately begin serving your static files with the correct
16 MIME type. The light-weight MIME::Types module is used to map file
17 extensions to IANA-registered MIME types.
19 Note that actions mapped to paths using periods (.) will still operate
22 You may further tweak the operation by adding configuration options,
25 ADVANCED CONFIGURATION
26 Configuration is completely optional and is specified within
27 MyApp->config->{static}. If you use any of these options, the module
28 will probably feel less "simple" to you!
30 Aborting request logging
31 Since Catalyst 5.50, there has been added support for dropping logging
32 for a request. This is enabled by default for static files, as static
33 requests tend to clutter the log output. However, if you want logging of
34 static requests, you can enable it by setting
35 MyApp->config->{static}->{no_logs} to 0.
37 Forcing directories into static mode
38 Define a list of top-level directories beneath your 'root' directory
39 that should always be served in static mode. Regular expressions may be
42 MyApp->config->{static}->{dirs} = [
47 Including additional directories
48 You may specify a list of directories in which to search for your static
49 files. The directories will be searched in order and will return the
50 first file found. Note that your root directory is not automatically
51 added to the search path when you specify an include_path. You should
52 use MyApp->config->{root} to add it.
54 MyApp->config->{static}->{include_path} = [
60 With the above setting, a request for the file /images/logo.jpg will
61 search for the following files, returning the first one found:
63 /path/to/overlay/images/logo.jpg
64 /dynamic/path/images/logo.jpg
65 /your/app/home/root/images/logo.jpg
67 The include path can contain a subroutine reference to dynamically
68 return a list of available directories. This method will receive the $c
69 object as a parameter and should return a reference to a list of
70 directories. Errors can be reported using die(). This method will be
71 called every time a file is requested that appears to be a static file
72 (i.e. it has an extension).
76 sub incpath_generator {
79 if ( $c->session->{customer_dir} ) {
80 return [ $c->session->{customer_dir} ];
82 die "No customer dir defined.";
86 Ignoring certain types of files
87 There are some file types you may not wish to serve as static files.
88 Most important in this category are your raw template files. By default,
89 files with the extensions tt, html, and xhtml will be ignored by
90 Static::Simple in the interest of security. If you wish to define your
91 own extensions to ignore, use the ignore_extensions option:
93 MyApp->config->{static}->{ignore_extensions} = [ qw/tt html xhtml/ ];
95 Ignoring entire directories
96 To prevent an entire directory from being served statically, you can use
97 the ignore_dirs option. This option contains a list of relative
98 directory paths to ignore. If using include_path, the path will be
99 checked against every included path.
101 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
103 For example, if combined with the above include_path setting, this
104 ignore_dirs value will ignore the following directories if they exist:
106 /path/to/overlay/tmpl
110 /your/app/home/root/tmpl
111 /your/app/home/root/css
114 To override or add to the default MIME types set by the MIME::Types
115 module, you may enter your own extension to MIME type mapping.
117 MyApp->config->{static}->{mime_types} = {
122 Apache integration and performance
123 Optionally, when running under mod_perl, Static::Simple can return
124 DECLINED on static files to allow Apache to serve the file. A check is
125 first done to make sure that Apache's DocumentRoot matches your Catalyst
126 root, and that you are not using any custom MIME types or multiple
127 roots. To enable the Apache support, you can set the following option.
129 MyApp->config->{static}->{use_apache} = 1;
131 By default this option is disabled because after several benchmarks it
132 appears that just serving the file from Catalyst is the better option.
133 On a 3K file, Catalyst appears to be around 25% faster, and is 42%
134 faster on a 10K file. My benchmarking was done using the following
135 'siege' command, so other benchmarks would be welcome!
137 siege -u http://server/static/css/10K.css -b -t 1M -c 1
139 For best static performance, you should still serve your static files
140 directly from Apache by defining a Location block similar to the
144 SetHandler default-handler
147 Bypassing other plugins
148 This plugin checks for a static file in the prepare_action stage. If the
149 request is for a static file, it will bypass all remaining
150 prepare_action steps. This means that by placing Static::Simple before
151 all other plugins, they will not execute when a static file is found.
152 This can be helpful by skipping session cookie checks for example. Or,
153 if you want some plugins to run even on static files, list them before
156 Currently, work done by plugins in any other prepare method will execute
159 Debugging information
160 Enable additional debugging information printed in the Catalyst log.
161 This is automatically enabled when running Catalyst in -Debug mode.
163 MyApp->config->{static}->{debug} = 1;
166 Catalyst, Catalyst::Plugin::Static,
167 <http://www.iana.org/assignments/media-types/>
170 Andy Grundman, <andy@hybridized.org>
173 Marcus Ramberg, <mramberg@cpan.org>
176 The authors of Catalyst::Plugin::Static:
182 For the include_path code from Template Toolkit:
187 This program is free software, you can redistribute it and/or modify it
188 under the same terms as Perl itself.