1 package Catalyst::Request;
4 use base 'Class::Accessor::Fast';
6 use IO::Socket qw[AF_INET inet_aton];
8 __PACKAGE__->mk_accessors(
9 qw/action address arguments cookies headers match method
10 protocol query_parameters secure snippets uri user/
14 *body_params = \&body_parameters;
16 *params = \¶meters;
17 *query_params = \&query_parameters;
20 sub content_encoding { shift->headers->content_encoding(@_) }
21 sub content_length { shift->headers->content_length(@_) }
22 sub content_type { shift->headers->content_type(@_) }
23 sub header { shift->headers->header(@_) }
24 sub referer { shift->headers->referer(@_) }
25 sub user_agent { shift->headers->user_agent(@_) }
29 Catalyst::Request - Catalyst Request Class
41 $req->body_parameters;
42 $req->content_encoding;
58 $req->query_parameters;
73 This is the Catalyst Request class, which provides a set of accessors to the
74 request data. The request object is prepared by the specialized Catalyst
75 Engine module thus hiding the details of the particular engine implementation.
84 Contains the requested action.
86 print $c->request->action;
90 Contains the remote address.
92 print $c->request->address
96 Shortcut for arguments
100 Returns a reference to an array containing the arguments.
102 print $c->request->arguments->[0];
104 For example, if your action was
106 package MyApp::C::Foo;
112 And the URI for the request was C<http://.../foo/moose/bah> the string C<bah>
113 would be the first and only argument.
117 Contains the URI base. This will always have a trailing slash.
119 If your application was queried with the URI C<http://localhost:3000/some/path>
120 then C<base> is C<http://localhost:3000/>.
125 my ( $self, $base ) = @_;
127 return $self->{base} unless $base;
129 $self->{base} = $base;
131 # set the value in path for backwards-compat
136 return $self->{base};
141 Contains the message body of the request unless Content-Type is
142 C<application/x-www-form-urlencoded> or C<multipart/form-data>.
144 print $c->request->body
149 my ( $self, $body ) = @_;
150 $self->{_context}->prepare_body;
151 return $self->{_body}->body;
154 =item $req->body_parameters
156 Returns a reference to a hash containing body parameters. Values can
157 be either a scalar or an arrayref containing scalars.
159 print $c->request->body_parameters->{field};
160 print $c->request->body_parameters->{field}->[0];
162 These are the paramaters from the POST part of the request, if any.
164 =item $req->body_params
166 An alias for body_parameters.
170 sub body_parameters {
171 my ( $self, $params ) = @_;
172 $self->{_context}->prepare_body;
173 $self->{body_parameters} = $params if $params;
174 return $self->{body_parameters};
177 =item $req->content_encoding
179 Shortcut to $req->headers->content_encoding
181 =item $req->content_length
183 Shortcut to $req->headers->content_length
185 =item $req->content_type
187 Shortcut to $req->headers->content_type
191 A convenient method to $req->cookies.
193 $cookie = $c->request->cookie('name');
194 @cookies = $c->request->cookie;
202 return keys %{ $self->cookies };
209 unless ( exists $self->cookies->{$name} ) {
213 return $self->cookies->{$name};
219 Returns a reference to a hash containing the cookies.
221 print $c->request->cookies->{mycookie}->value;
223 The cookies in the hash are indexed by name, and the values are C<CGI::Cookie>
228 Shortcut to $req->headers->header
232 Returns an L<HTTP::Headers> object containing the headers.
234 print $c->request->headers->header('X-Catalyst');
238 Lookup the current users DNS hostname.
240 print $c->request->hostname
247 if ( @_ == 0 && not $self->{hostname} ) {
249 gethostbyaddr( inet_aton( $self->address ), AF_INET );
253 $self->{hostname} = shift;
256 return $self->{hostname};
261 Shortcut for $req->body.
265 This contains the matching part of a regexp action. Otherwise
266 it returns the same as 'action'.
268 print $c->request->match;
272 Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
274 print $c->request->method;
278 Get request parameters with a CGI.pm-compatible param method. This
279 is a method for accessing parameters in $c->req->parameters.
281 $value = $c->request->param('foo');
282 @values = $c->request->param('foo');
283 @params = $c->request->param;
291 return keys %{ $self->parameters };
298 unless ( exists $self->parameters->{$param} ) {
299 return wantarray ? () : undef;
302 if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
304 ? @{ $self->parameters->{$param} }
305 : $self->parameters->{$param}->[0];
309 ? ( $self->parameters->{$param} )
310 : $self->parameters->{$param};
316 while ( my ( $field, $value ) = splice( @_, 0, 2 ) ) {
318 next unless defined $field;
320 if ( exists $self->parameters->{$field} ) {
321 for ( $self->parameters->{$field} ) {
322 $_ = [$_] unless ref($_) eq "ARRAY";
327 $self->parameters->{$field} = $value;
335 Shortcut for $req->parameters.
337 =item $req->parameters
339 Returns a reference to a hash containing parameters. Values can
340 be either a scalar or an arrayref containing scalars.
342 print $c->request->parameters->{field};
343 print $c->request->parameters->{field}->[0];
345 This is the combination of C<query_parameters> and C<body_parameters>.
350 my ( $self, $params ) = @_;
351 $self->{_context}->prepare_body;
352 $self->{parameters} = $params if $params;
353 return $self->{parameters};
360 print $c->request->path;
362 =item $req->path_info
364 alias for path, added for compability with L<CGI>
369 my ( $self, $params ) = @_;
372 $self->uri->path($params);
375 return $self->{path} if $self->{path};
378 my $path = $self->uri->path;
379 my $location = $self->base->path;
380 $path =~ s/^(\Q$location\E)?//;
381 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
383 $self->{path} = $path;
390 Contains the protocol.
392 =item $req->query_parameters
394 Returns a reference to a hash containing query parameters. Values can
395 be either a scalar or an arrayref containing scalars.
397 print $c->request->query_parameters->{field};
398 print $c->request->query_parameters->{field}->[0];
400 These are the parameters from the query string portion of the request's URI, if
403 =item $req->read( [$maxlength] )
405 Read a chunk of data from the request body. This method is designed to be
406 used in a while loop, reading $maxlength bytes on every call. $maxlength
407 defaults to the size of the request if not specified.
409 You have to set MyApp->config->{parse_on_demand} to use this directly.
413 sub read { shift->{_context}->read(@_); }
417 Shortcut to $req->headers->referer. Referring page.
421 Contains a boolean denoting whether the communication is secure.
425 Returns a reference to an array containing regex snippets.
427 my @snippets = @{ $c->request->snippets };
431 A convenient method to $req->uploads.
433 $upload = $c->request->upload('field');
434 @uploads = $c->request->upload('field');
435 @fields = $c->request->upload;
437 for my $upload ( $c->request->upload('field') ) {
438 print $upload->filename;
447 return keys %{ $self->uploads };
454 unless ( exists $self->uploads->{$upload} ) {
455 return wantarray ? () : undef;
458 if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
460 ? @{ $self->uploads->{$upload} }
461 : $self->uploads->{$upload}->[0];
465 ? ( $self->uploads->{$upload} )
466 : $self->uploads->{$upload};
472 while ( my ( $field, $upload ) = splice( @_, 0, 2 ) ) {
474 if ( exists $self->uploads->{$field} ) {
475 for ( $self->uploads->{$field} ) {
476 $_ = [$_] unless ref($_) eq "ARRAY";
477 push( @$_, $upload );
481 $self->uploads->{$field} = $upload;
489 Returns a reference to a hash containing uploads. Values can be either a
490 hashref or a arrayref containing C<Catalyst::Request::Upload> objects.
492 my $upload = $c->request->uploads->{field};
493 my $upload = $c->request->uploads->{field}->[0];
498 my ( $self, $uploads ) = @_;
499 $self->{_context}->prepare_body;
500 $self->{uploads} = $uploads if $uploads;
501 return $self->{uploads};
506 Returns a URI object for the request.
510 Contains the user name of user if authentication check was successful.
512 =item $req->user_agent
514 Shortcut to $req->headers->user_agent. User Agent version string.
520 Sebastian Riedel, C<sri@cpan.org>
521 Marcus Ramberg, C<mramberg@cpan.org>
525 This program is free software, you can redistribute it and/or modify
526 it under the same terms as Perl itself.