1 package Catalyst::Request;
3 use IO::Socket qw[AF_INET inet_aton];
13 use namespace::clean -except => 'meta';
15 with 'MooseX::Emulate::Class::Accessor::Fast';
17 has action => (is => 'rw');
18 has address => (is => 'rw');
19 has arguments => (is => 'rw', default => sub { [] });
20 has cookies => (is => 'rw', default => sub { {} });
21 has query_keywords => (is => 'rw');
22 has match => (is => 'rw');
23 has method => (is => 'rw');
24 has protocol => (is => 'rw');
25 has query_parameters => (is => 'rw', default => sub { {} });
26 has secure => (is => 'rw', default => 0);
27 has captures => (is => 'rw', default => sub { [] });
28 has uri => (is => 'rw', predicate => 'has_uri');
29 has user => (is => 'rw');
32 isa => 'HTTP::Headers',
33 handles => [qw(content_encoding content_length content_type header referer user_agent)],
34 default => sub { HTTP::Headers->new() },
40 # - Can we lose the before modifiers which just call prepare_body ?
41 # they are wasteful, slow us down and feel cluttery.
42 # Can we call prepare_body at BUILD time?
43 # Can we make _body an attribute, have the rest of
44 # these lazy build from there and kill all the direct hash access
45 # in Catalyst.pm and Engine.pm?
51 clearer => '_clear_context',
54 has body_parameters => (
58 default => sub { {} },
61 before body_parameters => sub {
63 $self->_context->prepare_body();
69 default => sub { {} },
76 default => sub { {} },
79 around parameters => sub {
80 my ($orig, $self, $params) = @_;
83 $self->_context->log->warn(
84 "Attempt to retrieve '$params' with req->params(), " .
85 "you probably meant to call req->param('$params')"
89 return $self->$orig($params);
100 return $self->path if $self->has_uri;
105 is => 'rw', clearer => '_clear_body', predicate => '_has_body',
107 # Eugh, ugly. Should just be able to rename accessor methods to 'body'
108 # and provide a custom reader..
111 $self->_context->prepare_body();
112 $self->_body(@_) if scalar @_;
113 return blessed $self->_body ? $self->_body->body : $self->_body;
122 gethostbyaddr( inet_aton( $self->address ), AF_INET ) || 'localhost'
126 has _path => ( is => 'rw', predicate => '_has_path', clearer => '_clear_path' );
128 sub args { shift->arguments(@_) }
129 sub body_params { shift->body_parameters(@_) }
130 sub input { shift->body(@_) }
131 sub params { shift->parameters(@_) }
132 sub query_params { shift->query_parameters(@_) }
133 sub path_info { shift->path(@_) }
134 sub snippets { shift->captures(@_) }
138 Catalyst::Request - provides information about the current client request
149 $req->body_parameters;
150 $req->content_encoding;
151 $req->content_length;
159 $req->query_keywords;
167 $req->query_parameters;
171 $req->captures; # previously knows as snippets
178 See also L<Catalyst>, L<Catalyst::Request::Upload>.
182 This is the Catalyst Request class, which provides an interface to data for the
183 current client request. The request object is prepared by L<Catalyst::Engine>,
184 thus hiding the details of the particular engine implementation.
190 [DEPRECATED] Returns the name of the requested action.
193 Use C<< $c->action >> instead (which returns a
194 L<Catalyst::Action|Catalyst::Action> object).
198 Returns the IP address of the client.
200 =head2 $req->arguments
202 Returns a reference to an array containing the arguments.
204 print $c->request->arguments->[0];
206 For example, if your action was
208 package MyApp::C::Foo;
214 and the URI for the request was C<http://.../foo/moose/bah>, the string C<bah>
215 would be the first and only argument.
217 Arguments just get passed through and B<don't> get unescaped automatically, so
218 you should do that explicitly.
222 Shortcut for arguments.
226 Contains the URI base. This will always have a trailing slash. Note that the
227 URI scheme (eg., http vs. https) must be determined through heuristics;
228 depending on your server configuration, it may be incorrect. See $req->secure
231 If your application was queried with the URI
232 C<http://localhost:3000/some/path> then C<base> is C<http://localhost:3000/>.
236 Returns the message body of the request, unless Content-Type is
237 C<application/x-www-form-urlencoded> or C<multipart/form-data>.
239 =head2 $req->body_parameters
241 Returns a reference to a hash containing body (POST) parameters. Values can
242 be either a scalar or an arrayref containing scalars.
244 print $c->request->body_parameters->{field};
245 print $c->request->body_parameters->{field}->[0];
247 These are the parameters from the POST part of the request, if any.
249 =head2 $req->body_params
251 Shortcut for body_parameters.
253 =head2 $req->content_encoding
255 Shortcut for $req->headers->content_encoding.
257 =head2 $req->content_length
259 Shortcut for $req->headers->content_length.
261 =head2 $req->content_type
263 Shortcut for $req->headers->content_type.
267 A convenient method to access $req->cookies.
269 $cookie = $c->request->cookie('name');
270 @cookies = $c->request->cookie;
278 return keys %{ $self->cookies };
285 unless ( exists $self->cookies->{$name} ) {
289 return $self->cookies->{$name};
295 Returns a reference to a hash containing the cookies.
297 print $c->request->cookies->{mycookie}->value;
299 The cookies in the hash are indexed by name, and the values are L<CGI::Cookie>
304 Shortcut for $req->headers->header.
308 Returns an L<HTTP::Headers> object containing the headers for the current request.
310 print $c->request->headers->header('X-Catalyst');
312 =head2 $req->hostname
314 Returns the hostname of the client.
318 Alias for $req->body.
320 =head2 $req->query_keywords
322 Contains the keywords portion of a query string, when no '=' signs are
325 http://localhost/path?some+keywords
327 $c->request->query_keywords will contain 'some keywords'
331 This contains the matching part of a Regex action. Otherwise
332 it returns the same as 'action', except for default actions,
333 which return an empty string.
337 Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
341 Returns GET and POST parameters with a CGI.pm-compatible param method. This
342 is an alternative method for accessing parameters in $c->req->parameters.
344 $value = $c->request->param( 'foo' );
345 @values = $c->request->param( 'foo' );
346 @params = $c->request->param;
348 Like L<CGI>, and B<unlike> earlier versions of Catalyst, passing multiple
349 arguments to this method, like this:
351 $c->request->param( 'foo', 'bar', 'gorch', 'quxx' );
353 will set the parameter C<foo> to the multiple values C<bar>, C<gorch> and
354 C<quxx>. Previously this would have added C<bar> as another value to C<foo>
355 (creating it if it didn't exist before), and C<quxx> as another value for
364 return keys %{ $self->parameters };
371 unless ( exists $self->parameters->{$param} ) {
372 return wantarray ? () : undef;
375 if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
377 ? @{ $self->parameters->{$param} }
378 : $self->parameters->{$param}->[0];
382 ? ( $self->parameters->{$param} )
383 : $self->parameters->{$param};
388 $self->parameters->{$field} = [@_];
392 =head2 $req->parameters
394 Returns a reference to a hash containing GET and POST parameters. Values can
395 be either a scalar or an arrayref containing scalars.
397 print $c->request->parameters->{field};
398 print $c->request->parameters->{field}->[0];
400 This is the combination of C<query_parameters> and C<body_parameters>.
404 Shortcut for $req->parameters.
408 Returns the path, i.e. the part of the URI after $req->base, for the current request.
410 =head2 $req->path_info
412 Alias for path, added for compatibility with L<CGI>.
417 my ( $self, @params ) = @_;
420 $self->uri->path(@params);
423 elsif ( $self->_has_path ) {
427 my $path = $self->uri->path;
428 my $location = $self->base->path;
429 $path =~ s/^(\Q$location\E)?//;
437 =head2 $req->protocol
439 Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current request.
441 =head2 $req->query_parameters
443 =head2 $req->query_params
445 Returns a reference to a hash containing query string (GET) parameters. Values can
446 be either a scalar or an arrayref containing scalars.
448 print $c->request->query_parameters->{field};
449 print $c->request->query_parameters->{field}->[0];
451 =head2 $req->read( [$maxlength] )
453 Reads a chunk of data from the request body. This method is intended to be
454 used in a while loop, reading $maxlength bytes on every call. $maxlength
455 defaults to the size of the request if not specified.
457 You have to set MyApp->config->{parse_on_demand} to use this directly.
461 Shortcut for $req->headers->referer. Returns the referring page.
465 Returns true or false, indicating whether the connection is secure
466 (https). Note that the URI scheme (eg., http vs. https) must be determined
467 through heuristics, and therefore the reliablity of $req->secure will depend
468 on your server configuration. If you are serving secure pages on the standard
469 SSL port (443) and/or setting the HTTPS environment variable, $req->secure
472 =head2 $req->captures
474 Returns a reference to an array containing captured args from chained
475 actions or regex captures.
477 my @captures = @{ $c->request->captures };
479 =head2 $req->snippets
481 C<captures> used to be called snippets. This is still available for backwards
482 compatibility, but is considered deprecated.
486 A convenient method to access $req->uploads.
488 $upload = $c->request->upload('field');
489 @uploads = $c->request->upload('field');
490 @fields = $c->request->upload;
492 for my $upload ( $c->request->upload('field') ) {
493 print $upload->filename;
502 return keys %{ $self->uploads };
509 unless ( exists $self->uploads->{$upload} ) {
510 return wantarray ? () : undef;
513 if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
515 ? @{ $self->uploads->{$upload} }
516 : $self->uploads->{$upload}->[0];
520 ? ( $self->uploads->{$upload} )
521 : $self->uploads->{$upload};
527 while ( my ( $field, $upload ) = splice( @_, 0, 2 ) ) {
529 if ( exists $self->uploads->{$field} ) {
530 for ( $self->uploads->{$field} ) {
531 $_ = [$_] unless ref($_) eq "ARRAY";
532 push( @$_, $upload );
536 $self->uploads->{$field} = $upload;
544 Returns a reference to a hash containing uploads. Values can be either a
545 L<Catalyst::Request::Upload> object, or an arrayref of
546 L<Catalyst::Request::Upload> objects.
548 my $upload = $c->request->uploads->{field};
549 my $upload = $c->request->uploads->{field}->[0];
553 Returns a URI object for the current request. Stringifies to the URI text.
555 =head2 $req->uri_with( { key => 'value' } );
557 Returns a rewritten URI object for the current request. Key/value pairs
558 passed in will override existing parameters. You can remove an existing
559 parameter by passing in an undef value. Unmodified pairs will be
565 my( $self, $args ) = @_;
567 carp( 'No arguments passed to uri_with()' ) unless $args;
569 foreach my $value ( values %$args ) {
570 next unless defined $value;
571 for ( ref $value eq 'ARRAY' ? @$value : $value ) {
573 utf8::encode( $_ ) if utf8::is_utf8($_);
577 my $uri = $self->uri->clone;
578 my %query = ( %{ $uri->query_form_hash }, %$args );
581 # remove undef values
582 map { defined $query{ $_ } ? ( $_ => $query{ $_ } ) : () } keys %query
589 Returns the currently logged in user. Deprecated. The method recommended for
590 newer plugins is $c->user.
592 =head2 $req->user_agent
594 Shortcut to $req->headers->user_agent. Returns the user agent (browser)
603 Catalyst Contributors, see Catalyst.pm
607 This program is free software, you can redistribute it and/or modify
608 it under the same terms as Perl itself.
612 __PACKAGE__->meta->make_immutable;