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 remote_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() },
43 clearer => '_clear_context',
46 has body_parameters => (
50 default => sub { {} },
56 default => sub { {} },
63 default => sub { {} },
67 # - Can we lose the before modifiers which just call prepare_body ?
68 # they are wasteful, slow us down and feel cluttery.
70 # Can we make _body an attribute, have the rest of
71 # these lazy build from there and kill all the direct hash access
72 # in Catalyst.pm and Engine.pm?
76 my $context = $self->_context || return;
77 $context->prepare_body;
78 } for qw/parameters body_parameters/;
80 around parameters => sub {
81 my ($orig, $self, $params) = @_;
84 $self->_context->log->warn(
85 "Attempt to retrieve '$params' with req->params(), " .
86 "you probably meant to call req->param('$params')"
90 return $self->$orig($params);
101 return $self->path if $self->has_uri;
106 is => 'rw', clearer => '_clear_body', predicate => '_has_body',
108 # Eugh, ugly. Should just be able to rename accessor methods to 'body'
109 # and provide a custom reader..
112 $self->_context->prepare_body();
113 croak 'body is a reader' if scalar @_;
114 return blessed $self->_body ? $self->_body->body : $self->_body;
123 gethostbyaddr( inet_aton( $self->address ), AF_INET ) || $self->address
127 has _path => ( is => 'rw', predicate => '_has_path', clearer => '_clear_path' );
129 # XXX: Deprecated in docs ages ago (2006), deprecated with warning in 5.8000 due
130 # to confusion between Engines and Plugin::Authentication. Remove in 5.8100?
131 has user => (is => 'rw');
133 sub args { shift->arguments(@_) }
134 sub body_params { shift->body_parameters(@_) }
135 sub input { shift->body(@_) }
136 sub params { shift->parameters(@_) }
137 sub query_params { shift->query_parameters(@_) }
138 sub path_info { shift->path(@_) }
139 sub snippets { shift->captures(@_) }
141 =for stopwords param params
145 Catalyst::Request - provides information about the current client request
156 $req->body_parameters;
157 $req->content_encoding;
158 $req->content_length;
166 $req->query_keywords;
174 $req->query_parameters;
178 $req->captures; # previously knows as snippets
185 See also L<Catalyst>, L<Catalyst::Request::Upload>.
189 This is the Catalyst Request class, which provides an interface to data for the
190 current client request. The request object is prepared by L<Catalyst::Engine>,
191 thus hiding the details of the particular engine implementation.
197 [DEPRECATED] Returns the name of the requested action.
200 Use C<< $c->action >> instead (which returns a
201 L<Catalyst::Action|Catalyst::Action> object).
205 Returns the IP address of the client.
207 =head2 $req->arguments
209 Returns a reference to an array containing the arguments.
211 print $c->request->arguments->[0];
213 For example, if your action was
215 package MyApp::Controller::Foo;
221 and the URI for the request was C<http://.../foo/moose/bah>, the string C<bah>
222 would be the first and only argument.
224 Arguments get automatically URI-unescaped for you.
228 Shortcut for L</arguments>.
232 Contains the URI base. This will always have a trailing slash. Note that the
233 URI scheme (e.g., http vs. https) must be determined through heuristics;
234 depending on your server configuration, it may be incorrect. See $req->secure
237 If your application was queried with the URI
238 C<http://localhost:3000/some/path> then C<base> is C<http://localhost:3000/>.
242 Returns the message body of the request, as returned by L<HTTP::Body>: a string,
243 unless Content-Type is C<application/x-www-form-urlencoded>, C<text/xml>, or
244 C<multipart/form-data>, in which case a L<File::Temp> object is returned.
246 =head2 $req->body_parameters
248 Returns a reference to a hash containing body (POST) parameters. Values can
249 be either a scalar or an arrayref containing scalars.
251 print $c->request->body_parameters->{field};
252 print $c->request->body_parameters->{field}->[0];
254 These are the parameters from the POST part of the request, if any.
256 =head2 $req->body_params
258 Shortcut for body_parameters.
260 =head2 $req->content_encoding
262 Shortcut for $req->headers->content_encoding.
264 =head2 $req->content_length
266 Shortcut for $req->headers->content_length.
268 =head2 $req->content_type
270 Shortcut for $req->headers->content_type.
274 A convenient method to access $req->cookies.
276 $cookie = $c->request->cookie('name');
277 @cookies = $c->request->cookie;
285 return keys %{ $self->cookies };
292 unless ( exists $self->cookies->{$name} ) {
296 return $self->cookies->{$name};
302 Returns a reference to a hash containing the cookies.
304 print $c->request->cookies->{mycookie}->value;
306 The cookies in the hash are indexed by name, and the values are L<CGI::Simple::Cookie>
311 Shortcut for $req->headers->header.
315 Returns an L<HTTP::Headers> object containing the headers for the current request.
317 print $c->request->headers->header('X-Catalyst');
319 =head2 $req->hostname
321 Returns the hostname of the client. Use $req->uri->host to get the hostname of the server.
325 Alias for $req->body.
327 =head2 $req->query_keywords
329 Contains the keywords portion of a query string, when no '=' signs are
332 http://localhost/path?some+keywords
334 $c->request->query_keywords will contain 'some keywords'
338 This contains the matching part of a Regex action. Otherwise
339 it returns the same as 'action', except for default actions,
340 which return an empty string.
344 Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
348 Returns GET and POST parameters with a CGI.pm-compatible param method. This
349 is an alternative method for accessing parameters in $c->req->parameters.
351 $value = $c->request->param( 'foo' );
352 @values = $c->request->param( 'foo' );
353 @params = $c->request->param;
355 Like L<CGI>, and B<unlike> earlier versions of Catalyst, passing multiple
356 arguments to this method, like this:
358 $c->request->param( 'foo', 'bar', 'gorch', 'quxx' );
360 will set the parameter C<foo> to the multiple values C<bar>, C<gorch> and
361 C<quxx>. Previously this would have added C<bar> as another value to C<foo>
362 (creating it if it didn't exist before), and C<quxx> as another value for
365 B<NOTE> this is considered a legacy interface and care should be taken when
366 using it. C<< scalar $c->req->param( 'foo' ) >> will return only the first
367 C<foo> param even if multiple are present; C<< $c->req->param( 'foo' ) >> will
368 return a list of as many are present, which can have unexpected consequences
369 when writing code of the form:
373 baz => $c->req->param( 'baz' ),
376 If multiple C<baz> parameters are provided this code might corrupt data or
377 cause a hash initialization error. For a more straightforward interface see
378 C<< $c->req->parameters >>.
386 return keys %{ $self->parameters };
393 unless ( exists $self->parameters->{$param} ) {
394 return wantarray ? () : undef;
397 if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
399 ? @{ $self->parameters->{$param} }
400 : $self->parameters->{$param}->[0];
404 ? ( $self->parameters->{$param} )
405 : $self->parameters->{$param};
410 $self->parameters->{$field} = [@_];
414 =head2 $req->parameters
416 Returns a reference to a hash containing GET and POST parameters. Values can
417 be either a scalar or an arrayref containing scalars.
419 print $c->request->parameters->{field};
420 print $c->request->parameters->{field}->[0];
422 This is the combination of C<query_parameters> and C<body_parameters>.
426 Shortcut for $req->parameters.
430 Returns the path, i.e. the part of the URI after $req->base, for the current request.
432 http://localhost/path/foo
434 $c->request->path will contain 'path/foo'
436 =head2 $req->path_info
438 Alias for path, added for compatibility with L<CGI>.
443 my ( $self, @params ) = @_;
446 $self->uri->path(@params);
449 elsif ( $self->_has_path ) {
453 my $path = $self->uri->path;
454 my $location = $self->base->path;
455 $path =~ s/^(\Q$location\E)?//;
463 =head2 $req->protocol
465 Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current request.
467 =head2 $req->query_parameters
469 =head2 $req->query_params
471 Returns a reference to a hash containing query string (GET) parameters. Values can
472 be either a scalar or an arrayref containing scalars.
474 print $c->request->query_parameters->{field};
475 print $c->request->query_parameters->{field}->[0];
477 =head2 $req->read( [$maxlength] )
479 Reads a chunk of data from the request body. This method is intended to be
480 used in a while loop, reading $maxlength bytes on every call. $maxlength
481 defaults to the size of the request if not specified.
483 You have to set MyApp->config(parse_on_demand => 1) to use this directly.
487 Shortcut for $req->headers->referer. Returns the referring page.
491 Returns true or false, indicating whether the connection is secure
492 (https). Note that the URI scheme (e.g., http vs. https) must be determined
493 through heuristics, and therefore the reliability of $req->secure will depend
494 on your server configuration. If you are serving secure pages on the standard
495 SSL port (443) and/or setting the HTTPS environment variable, $req->secure
498 =head2 $req->captures
500 Returns a reference to an array containing captured args from chained
501 actions or regex captures.
503 my @captures = @{ $c->request->captures };
505 =head2 $req->snippets
507 C<captures> used to be called snippets. This is still available for backwards
508 compatibility, but is considered deprecated.
512 A convenient method to access $req->uploads.
514 $upload = $c->request->upload('field');
515 @uploads = $c->request->upload('field');
516 @fields = $c->request->upload;
518 for my $upload ( $c->request->upload('field') ) {
519 print $upload->filename;
528 return keys %{ $self->uploads };
535 unless ( exists $self->uploads->{$upload} ) {
536 return wantarray ? () : undef;
539 if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
541 ? @{ $self->uploads->{$upload} }
542 : $self->uploads->{$upload}->[0];
546 ? ( $self->uploads->{$upload} )
547 : $self->uploads->{$upload};
553 while ( my ( $field, $upload ) = splice( @_, 0, 2 ) ) {
555 if ( exists $self->uploads->{$field} ) {
556 for ( $self->uploads->{$field} ) {
557 $_ = [$_] unless ref($_) eq "ARRAY";
558 push( @$_, $upload );
562 $self->uploads->{$field} = $upload;
570 Returns a reference to a hash containing uploads. Values can be either a
571 L<Catalyst::Request::Upload> object, or an arrayref of
572 L<Catalyst::Request::Upload> objects.
574 my $upload = $c->request->uploads->{field};
575 my $upload = $c->request->uploads->{field}->[0];
579 Returns a L<URI> object for the current request. Stringifies to the URI text.
581 =head2 $req->mangle_params( { key => 'value' }, $appendmode);
583 Returns a hashref of parameters stemming from the current request's params,
584 plus the ones supplied. Keys for which no current param exists will be
585 added, keys with undefined values will be removed and keys with existing
586 params will be replaced. Note that you can supply a true value as the final
587 argument to change behavior with regards to existing parameters, appending
588 values rather than replacing them.
592 # URI query params foo=1
593 my $hashref = $req->mangle_params({ foo => 2 });
594 # Result is query params of foo=2
598 # URI query params foo=1
599 my $hashref = $req->mangle_params({ foo => 2 }, 1);
600 # Result is query params of foo=1&foo=2
602 This is the code behind C<uri_with>.
607 my ($self, $args, $append) = @_;
609 carp('No arguments passed to mangle_params()') unless $args;
611 foreach my $value ( values %$args ) {
612 next unless defined $value;
613 for ( ref $value eq 'ARRAY' ? @$value : $value ) {
615 utf8::encode( $_ ) if utf8::is_utf8($_);
619 my %params = %{ $self->uri->query_form_hash };
620 foreach my $key (keys %{ $args }) {
621 my $val = $args->{$key};
624 if($append && exists($params{$key})) {
626 # This little bit of heaven handles appending a new value onto
627 # an existing one regardless if the existing value is an array
628 # or not, and regardless if the new value is an array or not
630 ref($params{$key}) eq 'ARRAY' ? @{ $params{$key} } : $params{$key},
631 ref($val) eq 'ARRAY' ? @{ $val } : $val
635 $params{$key} = $val;
639 # If the param wasn't defined then we delete it.
640 delete($params{$key});
648 =head2 $req->uri_with( { key => 'value' } );
650 Returns a rewritten URI object for the current request. Key/value pairs
651 passed in will override existing parameters. You can remove an existing
652 parameter by passing in an undef value. Unmodified pairs will be
655 You may also pass an optional second parameter that puts C<uri_with> into
658 $req->uri_with( { key => 'value' }, { mode => 'append' } );
660 See C<mangle_params> for an explanation of this behavior.
665 my( $self, $args, $behavior) = @_;
667 carp( 'No arguments passed to uri_with()' ) unless $args;
670 if((ref($behavior) eq 'HASH') && defined($behavior->{mode}) && ($behavior->{mode} eq 'append')) {
674 my $params = $self->mangle_params($args, $append);
676 my $uri = $self->uri->clone;
677 $uri->query_form($params);
682 =head2 $req->remote_user
684 Returns the value of the C<REMOTE_USER> environment variable.
686 =head2 $req->user_agent
688 Shortcut to $req->headers->user_agent. Returns the user agent (browser)
697 Catalyst Contributors, see Catalyst.pm
701 This library is free software. You can redistribute it and/or modify
702 it under the same terms as Perl itself.
706 __PACKAGE__->meta->make_immutable;