Plack::Middleware::Negotiate - Apply HTTP content negotiation as Plack middleware
version 0.06
builder { enable 'Negotiate', formats => { xml => { type => 'application/xml', charset => 'utf-8', }, html => { type => 'text/html', language => 'en' }, _ => { size => 0 } # default values for all formats }, parameter => 'format', # e.g. http://example.org/foo?format=xml extension => 'strip'; # e.g. http://example.org/foo.xml $app; # neither html nor xml requested };
Plack::Middleware::Negotiate applies HTTP content negotiation to a PSGI request. The PSGI environment key negotiate.format is set to the chosen format name. In addition to normal content negotiation one may enable explicit format selection with a path extension or query parameter. The middleware takes care for rewriting and restoring PATH_INFO if it is configured to detect and strip a format extension. The PSGI response is enriched with corresponding HTTP headers Content-Type and Content-Language unless these headers already exist.
negotiate.format
If used as pure application, this middleware returns a HTTP status code 406 if no format could be negotiated.
Creates a new negotiation middleware with a given set of formats. The argument parameter can be added to support explicit format selection with a query parameter. The argument extension can be used to support explicit format selection with a virtual file extension. Use format => 'strip' to strip a known format name from the request path and format => 'keep' to keep it. Each format can be defined with type, quality (defaults to 1), encoding, charset, and language. The special format name _ (underscore) is reserved to define default values for all formats.
parameter
extension
format => 'strip'
format => 'keep'
type
quality
encoding
charset
language
_
Formats can also be used to directly route the request to a PSGI application:
my $app = Plack::Middleware::Negotiate->new( formats => { json => { type => 'application/json', app => $json_app, }, html => { type => 'text/html', app => $html_app, } } );
Chooses a format based on a PSGI request. The request is first checked for explicit format selection via parameter and extension (if configured) and then passed to HTTP::Negotiate. Returns the format name. May modify the PSGI request environment keys PATH_INFO and SCRIPT_NAME if format was selected by extension set to strip, and strips the format query parameter from QUERY_STRING if parameter is set to a known format.
strip
format
If the format was specified, this method returns a hash with quality, type, encoding, charset, and language. Missing values are set to the default.
Returns a list of content variants to be used in HTTP::Negotiate. The return value is an array reference of array references, each with seven elements: format name, source quality, type, encoding, charset, language, and size. The size is always zero.
Add apropriate HTTP response headers for a format unless the headers are already given.
Plack::Middleware::Negotiate uses Log::Contextual to emit a logging message during content negotiation on logging level <trace>. Just set:
Log::Contextual
$ENV{PLACK_MIDDLEWARE_NEGOTIATE_TRACE} = 1;
The Content-Encoding HTTP response header is not automatically set on a response and content negotiation based on size is not supported. Feel free to comment on whether and how this middleware should support both.
Content negotiation in this module is based on HTTP::Negotiate. See HTTP::Headers::ActionPack::ContentNegotiation for an alternative approach. This module has some overlap with Plack::Middleware::SetAccept.
Jakob Voß <voss@gbv.de>
This software is copyright (c) 2013 by Jakob Voß.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Plack::Middleware::Negotiate, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Plack::Middleware::Negotiate
CPAN shell
perl -MCPAN -e shell install Plack::Middleware::Negotiate
For more information on module installation, please visit the detailed CPAN module installation guide.