NAME
Catalyst::Plugin::VersionedURI - add version component to uris
VERSION
version 1.2.0
SYNOPSIS
In your config file:
<Plugin::VersionedURI>
uri static/
mtime 0
</Plugin::VersionedURI>
In MyApp.pm
:
package MyApp;
use Catalyst qw/ VersionedURI /;
In the Apache config:
<Directory /home/myapp/static>
ExpiresActive on
ExpiresDefault "access plus 1 year"
</Directory>
DESCRIPTION
Catalyst::Plugin::VersionedURI
adds a versioned component to uris returned by uri_for()
matching a given set of regular expressions provided in the configuration file. E.g.,
$c->uri_for( '/static/images/foo.png' );
will, with the configuration used in the SYNOPSIS return
/static/images/foo.png?v=1.2.3
This can be useful, mainly, to have the static files of a site magically point to a new location upon new releases of the application, and thus bypass previously set expiration times.
The versioned component of the uri resolves to the version of the application.
CONFIGURATION
uri
The plugin's accepts any number of uri
configuration elements, which are taken as regular expressions to be matched against the uris. The regular expressions are implicitly anchored at the beginning of the uri, and at the end by a '/'. If not given, defaults to /static
.
mtime
If set to a true value, the plugin will use the file's modification time for versioning instead of the application's version. The modification time is checked only once for each file. If a file is changed after the application is started, the old version number will continue to be used. Checking the modification time on each uri, each time it is served, would result in considerable additional overhead.
include_path
A list of directories to search for files if you specify the mtime
flag. If no file is found, the application version is used. Defaults to MyApp-
config->{root}>.
in_path
If true, add the versioned element as part of the path (right after the matched uri). If false, the versioned element is added as a query parameter. For example, if we match on '/static', the base uri '/static/foo.png' will resolve to '/static/v1.2.3/foo.png' if 'in_path' is true, and '/static/foo.png?v=1.2.3' if false.
Defaults to false.
param
Name of the parameter to be used for the versioned element. Defaults to 'v'.
Not used if in_path is set to true.
WEB SERVER-SIDE CONFIGURATION
Of course, the redirection to a versioned uri is a sham to fool the browsers into refreshing their cache. If the path is modified because in_path is set to true, it's typical to configure the front-facing web server to point back to the same back-end directory.
Apache
To munge the paths back to the base directory, the Apache configuration can look like:
<Directory /home/myapp/static>
RewriteEngine on
RewriteRule ^v[0123456789._]+/(.*)$ /myapp/static/$1 [PT]
ExpiresActive on
ExpiresDefault "access plus 1 year"
</Directory>
YOU BROKE MY DEVELOPMENT SERVER, YOU INSENSITIVE CLOD!
If in_path is set to true, while the plugin is working fine with a web-server front-end, it's going to seriously cramp your style if you use, for example, the application's standalone server, as now all the newly-versioned uris are not going to resolve to anything. The obvious solution is, well, fairly obvious: remove the VersionedURI configuration stanza from your development configuration file.
If, for whatever reason, you absolutly want your application to deal with the versioned paths with or without the web server front-end, you can use Catalyst::Controller::VersionedURI, which will undo what Catalyst::Plugin::VersionedURI
toiled to shoe-horn in.
THANKS
Mark Grimes, Alexander Hartmaier.
SEE ALSO
- Blog entry introducing the module: http://babyl.dyndns.org/techblog/entry/versioned-uri.
- Catalyst::Controller::VersionedURI
AUTHOR
Yanick Champoux <yanick@babyl.dyndns.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Yanick Champoux.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.