[catagits/Catalyst-Runtime.git] / lib / Catalyst / Request.pm

package Catalyst::Request;

use strict;
use base 'Class::Accessor::Fast';

__PACKAGE__->mk_accessors(
    qw/action address arguments body base cookies headers hostname match
      method parameters path protocol secure snippets uploads/
);

*args   = \&arguments;
*input  = \&body;
*params = \&parameters;

sub content_encoding { shift->headers->content_encoding(@_) }
sub content_length   { shift->headers->content_length(@_)   }
sub content_type     { shift->headers->content_type(@_)     }
sub header           { shift->headers->header(@_)           }
sub referer          { shift->headers->referer(@_)          }
sub user_agent       { shift->headers->user_agent(@_)       }

=head1 NAME

Catalyst::Request - Catalyst Request Class

=head1 SYNOPSIS


    $req = $c->request;
    $req->action;
    $req->address;
    $req->args;
    $req->arguments;
    $req->base;
    $req->body;
    $req->content_encoding;
    $req->content_length;
    $req->content_type;
    $req->cookies;
    $req->header;
    $req->headers;
    $req->hostname;
    $req->input;
    $req->match;
    $req->method;
    $req->param;
    $req->params;
    $req->parameters;
    $req->path;
    $req->protocol;
    $req->referer;
    $req->secure;
    $req->snippets;
    $req->upload;
    $req->uploads;
    $req->user_agent

See also L<Catalyst>.

=head1 DESCRIPTION

This is the Catalyst Request class, which provides a set of accessors to the
request data.  The request object is prepared by the specialized Catalyst
Engine module thus hiding the details of the particular engine implementation.


=head1 METHODS

=over 4

=item $req->action

Contains the requested action.

    print $c->request->action;

=item $req->address

Contains the remote address.

    print $c->request->address

=item $req->args

Shortcut for arguments

=item $req->arguments

Returns a reference to an array containing the arguments.

    print $c->request->arguments->[0];

=item $req->base

Contains the url base. This will always have a trailing slash.

=item $req->body

Contains the message body of the request unless Content-Type is
C<application/x-www-form-urlencoded> or C<multipart/form-data>.

    print $c->request->body

=item $req->content_encoding

Shortcut to $req->headers->content_encoding

=item $req->content_length

Shortcut to $req->headers->content_length

=item $req->content_type

Shortcut to $req->headers->content_type

=item $req->cookies

Returns a reference to a hash containing the cookies.

    print $c->request->cookies->{mycookie}->value;

=item $req->header

Shortcut to $req->headers->header

=item $req->headers

Returns an L<HTTP::Headers> object containing the headers.

    print $c->request->headers->header('X-Catalyst');

=item $req->hostname

Contains the hostname of the remote user.

    print $c->request->hostname

=item $req->input

Shortcut for $req->body.

=item $req->match

This contains be the matching part of a regexp action. otherwise it
returns the same as 'action'.

    print $c->request->match;

=item $req->method

Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).

    print $c->request->method;

=item $req->param

Get request parameters with a CGI.pm like param method.

    $value  = $c->request->param('foo');
    @values = $c->request->param('foo');
    @params = $c->request->param;

=cut

sub param {
    my $self = shift;

    if ( @_ == 0 ) {
        return keys %{ $self->parameters };
    }

    if ( @_ == 1 ) {

        my $param = shift;

        unless ( exists $self->parameters->{$param} ) {
            return wantarray ? () : undef;
        }

        if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
            return (wantarray)
              ? @{ $self->parameters->{$param} }
              : $self->parameters->{$param}->[0];
        }
        else {
            return (wantarray)
              ? ( $self->parameters->{$param} )
              : $self->parameters->{$param};
        }
    }

    if ( @_ => 2  ) {

        while ( my ( $field, $value ) = splice( @_, 0, 2 ) ) {

            if ( exists $self->parameters->{$field} ) {
                for ( $self->parameters->{$field} ) {
                    $_ = [$_] unless ref($_) eq "ARRAY";
                    push( @$_, $value );
                }
            }
            else {
                $self->parameters->{$field} = $value;
            }
        }
    }
}

=item $req->params

Shortcut for $req->parameters.

=item $req->parameters

Returns a reference to a hash containing parameters. Values can
be either a scalar or a arrayref containing scalars.

    print $c->request->parameters->{field};
    print $c->request->parameters->{field}->[0];

=item $req->path

Contains the path.

    print $c->request->path;

=item $req->protocol

Contains the protocol.

=item $req->referer

Shortcut to $req->headers->referer. Referring page.

=item $req->secure

Contains a boolean whether the communciation is secure.

=item $req->snippets

Returns a reference to an array containing regex snippets.

    my @snippets = @{ $c->request->snippets };

=item $req->upload

A convenient method to $req->uploads.

    $upload  = $c->request->upload('field');
    @uploads = $c->request->upload('field');
    @fields  = $c->request->upload;

    for my $upload ( $c->request->upload('field') ) {
        print $upload->filename;
    }

=cut

sub upload {
    my $self = shift;

    if ( @_ == 0 ) {
        return keys %{ $self->uploads };
    }

    if ( @_ == 1 ) {

        my $upload = shift;

        unless ( exists $self->uploads->{$upload} ) {
            return wantarray ? () : undef;
        }

        if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
            return (wantarray)
              ? @{ $self->uploads->{$upload} }
              : $self->uploads->{$upload}->[0];
        }
        else {
            return (wantarray)
               ? ( $self->uploads->{$upload} )
               : $self->uploads->{$upload};
        }
    }

    if ( @_ => 2 ) {

        while ( my ( $field, $upload ) = splice( @_, 0, 2 ) ) {

            if ( exists $self->uploads->{$field} ) {
                for ( $self->uploads->{$field} ) {
                    $_ = [$_] unless ref($_) eq "ARRAY";
                    push( @$_, $upload );
                }
            }
            else {
                $self->uploads->{$field} = $upload;
            }
        }
    }
}

=item $req->uploads

Returns a reference to a hash containing uploads. Values can be either a
hashref or a arrayref containing C<Catalyst::Request::Upload> objects.

    my $upload = $c->request->uploads->{field};
    my $upload = $c->request->uploads->{field}->[0];

=item $req->user_agent

Shortcut to $req->headers->user_agent. User Agent version string.

=back

=head1 AUTHOR

Sebastian Riedel, C<sri@cpan.org>
Marcus Ramberg, C<mramberg@cpan.org>

=head1 COPYRIGHT

This program is free software, you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut

1;
Commit	Line	Data
fc7ec1d9	1	package Catalyst::Request;
	2
	3	use strict;
	4	use base 'Class::Accessor::Fast';
	5
	6	__PACKAGE__->mk_accessors(
e060fe05	7	qw/action address arguments body base cookies headers hostname match
bfde09a2	8	method parameters path protocol secure snippets uploads/
fc7ec1d9	9	);
	10
	11	*args = \&arguments;
e060fe05	12	*input = \&body;
fc7ec1d9	13	*params = \&parameters;
fc7ec1d9	14
f7e4e231	15	sub content_encoding { shift->headers->content_encoding(@_) }
	16	sub content_length { shift->headers->content_length(@_) }
	17	sub content_type { shift->headers->content_type(@_) }
	18	sub header { shift->headers->header(@_) }
	19	sub referer { shift->headers->referer(@_) }
	20	sub user_agent { shift->headers->user_agent(@_) }
	21
fc7ec1d9	22	=head1 NAME
	23
	24	Catalyst::Request - Catalyst Request Class
	25
	26	=head1 SYNOPSIS
	27
b22c6668	28
	29	$req = $c->request;
	30	$req->action;
	31	$req->address;
	32	$req->args;
	33	$req->arguments;
	34	$req->base;
06e1b616	35	$req->body;
b5176d9e	36	$req->content_encoding;
	37	$req->content_length;
	38	$req->content_type;
b22c6668	39	$req->cookies;
b5176d9e	40	$req->header;
b22c6668	41	$req->headers;
b22c6668	42	$req->hostname;
61bacdcc	43	$req->input;
b22c6668	44	$req->match;
b22c6668	45	$req->method;
e7c0c583	46	$req->param;
b22c6668	47	$req->params;
e7c0c583	48	$req->parameters;
b22c6668	49	$req->path;
bfde09a2	50	$req->protocol;
b5176d9e	51	$req->referer;
bfde09a2	52	$req->secure;
b22c6668	53	$req->snippets;
e7c0c583	54	$req->upload;
b22c6668	55	$req->uploads;
b5176d9e	56	$req->user_agent
b22c6668	57
b22c6668	58	See also L<Catalyst>.
fc7ec1d9	59
	60	=head1 DESCRIPTION
	61
b22c6668	62	This is the Catalyst Request class, which provides a set of accessors to the
	63	request data. The request object is prepared by the specialized Catalyst
	64	Engine module thus hiding the details of the particular engine implementation.
	65
	66
	67	=head1 METHODS
fc7ec1d9	68
b22c6668	69	=over 4
fc7ec1d9	70
b22c6668	71	=item $req->action
fc7ec1d9	72
61b1e958	73	Contains the requested action.
fc7ec1d9	74
	75	print $c->request->action;
	76
b22c6668	77	=item $req->address
0556eb49	78
	79	Contains the remote address.
	80
	81	print $c->request->address
	82
b22c6668	83	=item $req->args
b22c6668	84
61b1e958	85	Shortcut for arguments
	86
	87	=item $req->arguments
	88
b22c6668	89	Returns a reference to an array containing the arguments.
fc7ec1d9	90
	91	print $c->request->arguments->[0];
	92
b22c6668	93	=item $req->base
fc7ec1d9	94
61b1e958	95	Contains the url base. This will always have a trailing slash.
fc7ec1d9	96
06e1b616	97	=item $req->body
06e1b616	98
e060fe05	99	Contains the message body of the request unless Content-Type is
	100	C<application/x-www-form-urlencoded> or C<multipart/form-data>.
	101
	102	print $c->request->body
06e1b616	103
b5176d9e	104	=item $req->content_encoding
	105
	106	Shortcut to $req->headers->content_encoding
	107
	108	=item $req->content_length
	109
	110	Shortcut to $req->headers->content_length
	111
	112	=item $req->content_type
	113
	114	Shortcut to $req->headers->content_type
	115
b22c6668	116	=item $req->cookies
fc7ec1d9	117
b22c6668	118	Returns a reference to a hash containing the cookies.
fc7ec1d9	119
	120	print $c->request->cookies->{mycookie}->value;
	121
b5176d9e	122	=item $req->header
	123
	124	Shortcut to $req->headers->header
	125
b22c6668	126	=item $req->headers
fc7ec1d9	127
b22c6668	128	Returns an L<HTTP::Headers> object containing the headers.
fc7ec1d9	129
	130	print $c->request->headers->header('X-Catalyst');
	131
b22c6668	132	=item $req->hostname
0556eb49	133
61b1e958	134	Contains the hostname of the remote user.
0556eb49	135
	136	print $c->request->hostname
	137
61bacdcc	138	=item $req->input
61bacdcc	139
e060fe05	140	Shortcut for $req->body.
61bacdcc	141
b22c6668	142	=item $req->match
fc7ec1d9	143
e7c0c583	144	This contains be the matching part of a regexp action. otherwise it
61b1e958	145	returns the same as 'action'.
fc7ec1d9	146
	147	print $c->request->match;
	148
b5176d9e	149	=item $req->method
	150
	151	Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
	152
e7c0c583	153	print $c->request->method;
	154
	155	=item $req->param
	156
	157	Get request parameters with a CGI.pm like param method.
	158
	159	$value = $c->request->param('foo');
	160	@values = $c->request->param('foo');
	161	@params = $c->request->param;
	162
	163	=cut
	164
	165	sub param {
	166	my $self = shift;
	167
	168	if ( @_ == 0 ) {
	169	return keys %{ $self->parameters };
	170	}
	171
bfde09a2	172	if ( @_ == 1 ) {
e7c0c583	173
bfde09a2	174	my $param = shift;
6bd2b72c	175
bfde09a2	176	unless ( exists $self->parameters->{$param} ) {
	177	return wantarray ? () : undef;
	178	}
	179
	180	if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
	181	return (wantarray)
	182	? @{ $self->parameters->{$param} }
	183	: $self->parameters->{$param}->[0];
	184	}
	185	else {
	186	return (wantarray)
	187	? ( $self->parameters->{$param} )
	188	: $self->parameters->{$param};
	189	}
d7945f32	190	}
bfde09a2	191
	192	if ( @_ => 2 ) {
	193
	194	while ( my ( $field, $value ) = splice( @_, 0, 2 ) ) {
	195
	196	if ( exists $self->parameters->{$field} ) {
	197	for ( $self->parameters->{$field} ) {
	198	$_ = [$_] unless ref($_) eq "ARRAY";
	199	push( @$_, $value );
	200	}
	201	}
	202	else {
	203	$self->parameters->{$field} = $value;
	204	}
	205	}
d7945f32	206	}
e7c0c583	207	}
b5176d9e	208
b22c6668	209	=item $req->params
fc7ec1d9	210
61b1e958	211	Shortcut for $req->parameters.
	212
	213	=item $req->parameters
	214
e7c0c583	215	Returns a reference to a hash containing parameters. Values can
e7c0c583	216	be either a scalar or a arrayref containing scalars.
fc7ec1d9	217
e7c0c583	218	print $c->request->parameters->{field};
e7c0c583	219	print $c->request->parameters->{field}->[0];
fc7ec1d9	220
b22c6668	221	=item $req->path
fc7ec1d9	222
	223	Contains the path.
	224
	225	print $c->request->path;
	226
bfde09a2	227	=item $req->protocol
	228
	229	Contains the protocol.
	230
b5176d9e	231	=item $req->referer
fc7ec1d9	232
61b1e958	233	Shortcut to $req->headers->referer. Referring page.
fc7ec1d9	234
bfde09a2	235	=item $req->secure
	236
	237	Contains a boolean whether the communciation is secure.
	238
b22c6668	239	=item $req->snippets
fc7ec1d9	240
b22c6668	241	Returns a reference to an array containing regex snippets.
fc7ec1d9	242
	243	my @snippets = @{ $c->request->snippets };
	244
e7c0c583	245	=item $req->upload
	246
	247	A convenient method to $req->uploads.
	248
	249	$upload = $c->request->upload('field');
	250	@uploads = $c->request->upload('field');
	251	@fields = $c->request->upload;
bfde09a2	252
e7c0c583	253	for my $upload ( $c->request->upload('field') ) {
146554c5	254	print $upload->filename;
e7c0c583	255	}
	256
	257	=cut
	258
	259	sub upload {
	260	my $self = shift;
	261
	262	if ( @_ == 0 ) {
	263	return keys %{ $self->uploads };
	264	}
	265
bfde09a2	266	if ( @_ == 1 ) {
e7c0c583	267
bfde09a2	268	my $upload = shift;
	269
	270	unless ( exists $self->uploads->{$upload} ) {
	271	return wantarray ? () : undef;
	272	}
6bd2b72c	273
bfde09a2	274	if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
	275	return (wantarray)
	276	? @{ $self->uploads->{$upload} }
	277	: $self->uploads->{$upload}->[0];
	278	}
	279	else {
	280	return (wantarray)
	281	? ( $self->uploads->{$upload} )
	282	: $self->uploads->{$upload};
	283	}
d7945f32	284	}
bfde09a2	285
	286	if ( @_ => 2 ) {
	287
	288	while ( my ( $field, $upload ) = splice( @_, 0, 2 ) ) {
	289
	290	if ( exists $self->uploads->{$field} ) {
	291	for ( $self->uploads->{$field} ) {
	292	$_ = [$_] unless ref($_) eq "ARRAY";
	293	push( @$_, $upload );
	294	}
	295	}
	296	else {
	297	$self->uploads->{$field} = $upload;
	298	}
	299	}
e7c0c583	300	}
	301	}
	302
b22c6668	303	=item $req->uploads
fc7ec1d9	304
bfde09a2	305	Returns a reference to a hash containing uploads. Values can be either a
146554c5	306	hashref or a arrayref containing C<Catalyst::Request::Upload> objects.
e7c0c583	307
	308	my $upload = $c->request->uploads->{field};
	309	my $upload = $c->request->uploads->{field}->[0];
	310
b5176d9e	311	=item $req->user_agent
b5176d9e	312
61b1e958	313	Shortcut to $req->headers->user_agent. User Agent version string.
b5176d9e	314
b22c6668	315	=back
b22c6668	316
fc7ec1d9	317	=head1 AUTHOR
	318
	319	Sebastian Riedel, C<sri@cpan.org>
61b1e958	320	Marcus Ramberg, C<mramberg@cpan.org>
fc7ec1d9	321
	322	=head1 COPYRIGHT
	323
e7c0c583	324	This program is free software, you can redistribute it and/or modify
61b1e958	325	it under the same terms as Perl itself.
fc7ec1d9	326
	327	=cut
	328
	329	1;