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 parameters 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;
285 Like L<CGI>, and B<unlike> previous versions of Catalyst, passing multiple
286 arguments to this method, like this:
288 $c->request( 'foo', 'bar', 'gorch', 'quxx' );
290 will set the parameter C<foo> to the multiple values C<bar>, C<gorch> and
291 C<quxx>. Previously this would have added C<bar> as another value to C<foo>
292 (creating it if it didn't exist before), and C<quxx> as another value for C<gorch>.
300 return keys %{ $self->parameters };
307 unless ( exists $self->parameters->{$param} ) {
308 return wantarray ? () : undef;
311 if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
313 ? @{ $self->parameters->{$param} }
314 : $self->parameters->{$param}->[0];
318 ? ( $self->parameters->{$param} )
319 : $self->parameters->{$param};
324 $self->parameters->{$field} = [@_];
330 Shortcut for $req->parameters.
332 =item $req->parameters
334 Returns a reference to a hash containing parameters. Values can
335 be either a scalar or an arrayref containing scalars.
337 print $c->request->parameters->{field};
338 print $c->request->parameters->{field}->[0];
340 This is the combination of C<query_parameters> and C<body_parameters>.
345 my ( $self, $params ) = @_;
346 $self->{_context}->prepare_body;
347 $self->{parameters} = $params if $params;
348 return $self->{parameters};
355 print $c->request->path;
357 =item $req->path_info
359 alias for path, added for compability with L<CGI>
364 my ( $self, $params ) = @_;
367 $self->uri->path($params);
370 return $self->{path} if $self->{path};
373 my $path = $self->uri->path;
374 my $location = $self->base->path;
375 $path =~ s/^(\Q$location\E)?//;
376 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
378 $self->{path} = $path;
385 Contains the protocol.
387 =item $req->query_parameters
389 Returns a reference to a hash containing query parameters. Values can
390 be either a scalar or an arrayref containing scalars.
392 print $c->request->query_parameters->{field};
393 print $c->request->query_parameters->{field}->[0];
395 These are the parameters from the query string portion of the request's URI, if
398 =item $req->read( [$maxlength] )
400 Read a chunk of data from the request body. This method is designed to be
401 used in a while loop, reading $maxlength bytes on every call. $maxlength
402 defaults to the size of the request if not specified.
404 You have to set MyApp->config->{parse_on_demand} to use this directly.
408 sub read { shift->{_context}->read(@_); }
412 Shortcut to $req->headers->referer. Referring page.
416 Contains a boolean denoting whether the communication is secure.
420 Returns a reference to an array containing regex snippets.
422 my @snippets = @{ $c->request->snippets };
426 A convenient method to $req->uploads.
428 $upload = $c->request->upload('field');
429 @uploads = $c->request->upload('field');
430 @fields = $c->request->upload;
432 for my $upload ( $c->request->upload('field') ) {
433 print $upload->filename;
442 return keys %{ $self->uploads };
449 unless ( exists $self->uploads->{$upload} ) {
450 return wantarray ? () : undef;
453 if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
455 ? @{ $self->uploads->{$upload} }
456 : $self->uploads->{$upload}->[0];
460 ? ( $self->uploads->{$upload} )
461 : $self->uploads->{$upload};
467 while ( my ( $field, $upload ) = splice( @_, 0, 2 ) ) {
469 if ( exists $self->uploads->{$field} ) {
470 for ( $self->uploads->{$field} ) {
471 $_ = [$_] unless ref($_) eq "ARRAY";
472 push( @$_, $upload );
476 $self->uploads->{$field} = $upload;
484 Returns a reference to a hash containing uploads. Values can be either a
485 hashref or a arrayref containing C<Catalyst::Request::Upload> objects.
487 my $upload = $c->request->uploads->{field};
488 my $upload = $c->request->uploads->{field}->[0];
493 my ( $self, $uploads ) = @_;
494 $self->{_context}->prepare_body;
495 $self->{uploads} = $uploads if $uploads;
496 return $self->{uploads};
501 Returns a URI object for the request.
505 Contains the user name of user if authentication check was successful.
507 =item $req->user_agent
509 Shortcut to $req->headers->user_agent. User Agent version string.
515 Sebastian Riedel, C<sri@cpan.org>
516 Marcus Ramberg, C<mramberg@cpan.org>
520 This program is free software, you can redistribute it and/or modify
521 it under the same terms as Perl itself.