NAME

Plack::Middleware::Rewrite - mod_rewrite for Plack

VERSION

version 1.002

SYNOPSIS

# in app.psgi
use Plack::Builder;

builder {
    enable 'Rewrite', rules => sub {
        s{^/here(?=/|$)}{/there};

        return 301
            if s{^/foo/?$}{/bar/}
            or s{^/baz/?$}{/quux/};

        return 201 if $_ eq '/favicon.ico';

        return [200, [qw(Content-Type text/plain)], ['You found it!']]
           if $_ eq '/easter-egg';

        return sub { $_->set( 'Content-Type', 'application/xhtml+xml' ) }
            if $_[0]{'HTTP_ACCEPT'} =~ m{application/xhtml\+xml(?!\s*;\s*q=0)}
    };
    $app;
};

DESCRIPTION

This middleware provides a convenient way to modify requests in flight in Plack apps. Rewrite rules are simply written in Perl, which means everything that can be done with mod_rewrite can be done with this middleware much more intuitively (if in syntactically wordier ways). Its primary purpose is rewriting paths, but almost anything is possible very easily.

CONFIGURATIONS

rules

rules takes a reference to a function that will be called on each request. When it is, the PATH_INFO is aliased to $_, so that you can easily use regexp matches and subtitutions to examine and modify it. The PSGI envrionment will be passed as its first and only argument.

This function can return a value that looks like an HTTP status to stop the request from being processed further. In that case an empty response with the returned status will be sent to the browser. If it is a redirect status, then the rewritten PATH_INFO will be used as the redirect destination.

Alternatively it can return an array: a regular PSGI response, except that you may omit either or both the headers and body elements. (Empty ones will be supplied for you, for convenience.)

A third option is to return a reference to a function. This function will be called after the request has been processed, with $_ aliased to a Plack::Util::headers object for the response, for convenient alteration of headers. The PSGI environment is, again, passed as its first and only argument.

AUTHOR

Aristotle Pagaltzis <pagaltzis@gmx.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Aristotle Pagaltzis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.