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