[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 user/
);

*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;
    $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 ( @_ > 1 ) {

        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 ( @_ > 1 ) {

        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

Contains the user name of user if authentication check was successful.

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