[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->uri;
    $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->uri

Shortcut for C<< $req->base . $req->path >>.

=cut

sub uri {
    my $self = shift;
    my $path = shift || $self->path || '';
    return $self->base . $path;
}

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