view release on metacpan or  search on metacpan

I18N.pm  view on Meta::CPAN

package Apache::Request::I18N;

use 5.008;
use strict;
use warnings;

use Apache::Request 0.32;
use Carp;
use Encode qw(decode_utf8 encode_utf8);

our @ISA = 'Apache::Request';

our $VERSION = '0.08';


=head1 NAME

Apache::Request::I18N - Internationalization extension to Apache::Request


=head1 SYNOPSIS

  use Apache::Request::I18N;
  my $apr = Apache::Request::I18N->new($r, DECODE_PARMS => 'utf-8');

Or, add something like this to your Apache F<httpd.conf>:

  PerlModule Apache::Request::I18N;

  <Location ...>
  SetHandler  perl-script
  PerlHandler Apache::Request::I18N <your other handlers ...>
  PerlSetVar  DecodeParms  utf-8
  </Location>


=head1 DESCRIPTION

I<Apache::Request::I18N> adds transparent support over I<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 I<Apache::Request>, it can be used as a
drop-in replacement.  (It is not a B<perfect> replacement, though; see
L<"COMPATIBILITY ISSUES"> below.)  It can also be used in a I<PerlHandler>
directive, in which case all subsequent handlers will -- if they play nicely
-- automatically see the converted names and values.


=head1 CONSTRUCTORS

=over 2

=item new( REQ [, OPTIONS ] )

Creates and returns a new I<Apache::Request::I18N> object.  REQ is the
I<Apache> or I<Apache::Request> associated with the current request.

OPTIONS is an optional list of name/value pairs.  Each option also has a
corresponding I<mod_perl> variable (listed in parentheses) that can be set via
I<PerlSetVar> in F<httpd.conf>.  Values in OPTIONS take precedence.  The
available options are:

=over 4

=item DECODE_PARMS (I<DecodeParms>)

I<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 I<Encode> module (see L<Encode::Supported> for more details).

=item ENCODE_PARMS (I<EncodeParms>)

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.

=back

I<Apache::Request> options can also be included (although they will be ignored
if REQ is already an I<Apache::Request> object).

=cut

sub new {
	my ($class, $r, %args) = @_;

	my $self = bless {
			_decode_parms => delete $args{DECODE_PARMS}
					|| $r->dir_config('DecodeParms'),
			_encode_parms => delete $args{ENCODE_PARMS}
					|| $r->dir_config('EncodeParms'),
		}, $class;
	
	croak "The DECODE_PARMS parameter is currently required"
		unless $self->decode_parms;
	
	$r = Apache::Request->new($r, %args)