Apache::Request::I18N - Internationalization extension to Apache::Request
use Apache::Request::I18N; my $apr = Apache::Request::I18N->new($r, DECODE_PARMS => 'utf-8');
Or, add something like this to your Apache httpd.conf:
PerlModule Apache::Request::I18N; <Location ...> SetHandler perl-script PerlHandler Apache::Request::I18N <your other handlers ...> PerlSetVar DecodeParms utf-8 </Location>
Apache::Request::I18N adds transparent support over Apache::Request for internationalized GET/POST parameters. Form field names and values are automatically decoded and converted either to Perl's internal UTF-8 format, or to another character encoding.
Since this module inherits from Apache::Request, it can be used as a drop-in replacement. (It is not a perfect replacement, though; see "COMPATIBILITY ISSUES" below.) It can also be used in a PerlHandler directive, in which case all subsequent handlers will -- if they play nicely -- automatically see the converted names and values.
Creates and returns a new Apache::Request::I18N object. REQ is the Apache or Apache::Request associated with the current request.
OPTIONS is an optional list of name/value pairs. Each option also has a corresponding mod_perl variable (listed in parentheses) that can be set via PerlSetVar in httpd.conf. Values in OPTIONS take precedence. The available options are:
Required. Declares the character encoding that will be used by default when decoding form field names and values. This character encoding must be supported by the Encode module (see Encode::Supported for more details).
Declares the character encoding that will be used to re-encode form field names and values. If omitted, names and values will be in Perl's own internal UTF-8 format.
Apache::Request options can also be included (although they will be ignored if REQ is already an Apache::Request object).
Equivalent to the instance() method in Apache::Request, except that this method will return a Apache::Request::I18N object. Subsequent calls to Apache::Request->instance() will also return the same object. It is allowed to call Apache::Request->instance() beforehand.
Almost all Apache::Request methods are supported (see "COMPATIBILITY ISSUES" below for a list of exceptions), and will properly return values according to ENCODE_PARMS. (Apache methods, like args(), are not affected by this module.)
All arguments passed to a method must be encoded to ENCODE_PARMS beforehand, unless ENCODE_PARMS is empty. This also applies to each key/value of any Apache::Table passed to parms().
Uploads returned by the upload() method are Apache::Upload::I18N objects; they behave like Apache::Upload objects, and their name() and filename() methods will return values according to ENCODE_PARMS.
(This is however not the case within the upload hook; see "BUGS" below.)
This module provides a simple Apache handler that can be used in a PerlHandler directive. This is useful when used in combination with other handlers, which will then automatically access the decoded values. (This works as long as each handler takes care to call instance() instead of creating a new object.)
For example, you can use this module in combination with Mason:
SetHandler perl-script PerlHandler +Apache::Request::I18N +HTML::Mason::ApacheHandler PerlSetVar DecodeParms EUC-JP
Each Mason component will now see its arguments as true Perl character strings instead of EUC-JP bytes strings.
Conversely, since some user-agents are known to encode such values via RFC 2047, we attempt decoding if possible. This means that a value supplied by a standard-compliant user-agent may be wrongly decoded.
Similarly, the Content-Transfer-Encoding header is also ignored.
<FORM METHOD=post ENCTYPE="multipart/form-data" ACTION=".../my_script?foo=1"> <INPUT NAME="foo" ...> ...
You should also avoid mixing file uploads and regular input within a single field name. In other words, don't try this either:
<INPUT TYPE=text NAME="foo"> <INPUT TYPE=file NAME="foo">
<http://ppewww.ph.gla.ac.uk/~flavell/charset/form-i18n.html> RFC 1522 - MIME (Multipurpose Internet Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text RFC 1806 - Communicating Presentation Information in Internet Messages: The Content-Disposition Header [2.3] RFC 1866 - Hypertext Markup Language - 2.0 [8.2.1] RFC 1867 - Form-based File Upload in HTML [3.3, 5.11] RFC 2047 - MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text  RFC 2070 - Internationalization of the Hypertext Markup Language [5.2] RFC 2183 - Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field [2, 2.3] RFC 2231 - MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations RFC 2388 - Returning Values from Forms: multipart/form-data
Frédéric Brière, <email@example.com>
Copyright (C) 2005, 2006 by Frédéric Brière
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.