[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 ) ) {
        
            next unless defined $field;

            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
bfde09a2	196	while ( my ( $field, $value ) = splice( @_, 0, 2 ) ) {
a4def412	197
a4def412	198	next unless defined $field;
bfde09a2	199
	200	if ( exists $self->parameters->{$field} ) {
	201	for ( $self->parameters->{$field} ) {
	202	$_ = [$_] unless ref($_) eq "ARRAY";
	203	push( @$_, $value );
	204	}
	205	}
	206	else {
	207	$self->parameters->{$field} = $value;
	208	}
	209	}
d7945f32	210	}
e7c0c583	211	}
b5176d9e	212
b22c6668	213	=item $req->params
fc7ec1d9	214
61b1e958	215	Shortcut for $req->parameters.
	216
	217	=item $req->parameters
	218
e7c0c583	219	Returns a reference to a hash containing parameters. Values can
e7c0c583	220	be either a scalar or a arrayref containing scalars.
fc7ec1d9	221
e7c0c583	222	print $c->request->parameters->{field};
e7c0c583	223	print $c->request->parameters->{field}->[0];
fc7ec1d9	224
b22c6668	225	=item $req->path
fc7ec1d9	226
	227	Contains the path.
	228
	229	print $c->request->path;
	230
bfde09a2	231	=item $req->protocol
	232
	233	Contains the protocol.
	234
b5176d9e	235	=item $req->referer
fc7ec1d9	236
61b1e958	237	Shortcut to $req->headers->referer. Referring page.
fc7ec1d9	238
bfde09a2	239	=item $req->secure
	240
	241	Contains a boolean whether the communciation is secure.
	242
b22c6668	243	=item $req->snippets
fc7ec1d9	244
b22c6668	245	Returns a reference to an array containing regex snippets.
fc7ec1d9	246
	247	my @snippets = @{ $c->request->snippets };
	248
e7c0c583	249	=item $req->upload
	250
	251	A convenient method to $req->uploads.
	252
	253	$upload = $c->request->upload('field');
	254	@uploads = $c->request->upload('field');
	255	@fields = $c->request->upload;
bfde09a2	256
e7c0c583	257	for my $upload ( $c->request->upload('field') ) {
146554c5	258	print $upload->filename;
e7c0c583	259	}
	260
	261	=cut
	262
	263	sub upload {
	264	my $self = shift;
	265
	266	if ( @_ == 0 ) {
	267	return keys %{ $self->uploads };
	268	}
	269
bfde09a2	270	if ( @_ == 1 ) {
e7c0c583	271
bfde09a2	272	my $upload = shift;
	273
	274	unless ( exists $self->uploads->{$upload} ) {
	275	return wantarray ? () : undef;
	276	}
6bd2b72c	277
bfde09a2	278	if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
	279	return (wantarray)
	280	? @{ $self->uploads->{$upload} }
	281	: $self->uploads->{$upload}->[0];
	282	}
	283	else {
	284	return (wantarray)
	285	? ( $self->uploads->{$upload} )
	286	: $self->uploads->{$upload};
	287	}
d7945f32	288	}
bfde09a2	289
a4f5c51e	290	if ( @_ > 1 ) {
bfde09a2	291
	292	while ( my ( $field, $upload ) = splice( @_, 0, 2 ) ) {
	293
	294	if ( exists $self->uploads->{$field} ) {
	295	for ( $self->uploads->{$field} ) {
	296	$_ = [$_] unless ref($_) eq "ARRAY";
	297	push( @$_, $upload );
	298	}
	299	}
	300	else {
	301	$self->uploads->{$field} = $upload;
	302	}
	303	}
e7c0c583	304	}
	305	}
	306
b22c6668	307	=item $req->uploads
fc7ec1d9	308
bfde09a2	309	Returns a reference to a hash containing uploads. Values can be either a
146554c5	310	hashref or a arrayref containing C<Catalyst::Request::Upload> objects.
e7c0c583	311
	312	my $upload = $c->request->uploads->{field};
	313	my $upload = $c->request->uploads->{field}->[0];
	314
77d12cae	315	=item $req->uri
	316
	317	Shortcut for C<< $req->base . $req->path >>.
	318
	319	=cut
	320
	321	sub uri {
	322	my $self = shift;
	323	my $path = shift \|\| $self->path \|\| '';
	324	return $self->base . $path;
	325	}
	326
66294129	327	=item $req->user
	328
	329	Contains the user name of user if authentication check was successful.
	330
b5176d9e	331	=item $req->user_agent
b5176d9e	332
61b1e958	333	Shortcut to $req->headers->user_agent. User Agent version string.
b5176d9e	334
b22c6668	335	=back
b22c6668	336
fc7ec1d9	337	=head1 AUTHOR
	338
	339	Sebastian Riedel, C<sri@cpan.org>
61b1e958	340	Marcus Ramberg, C<mramberg@cpan.org>
fc7ec1d9	341
	342	=head1 COPYRIGHT
	343
e7c0c583	344	This program is free software, you can redistribute it and/or modify
61b1e958	345	it under the same terms as Perl itself.
fc7ec1d9	346
	347	=cut
	348
	349	1;