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 $self->_body(@_) if scalar @_;
114 return blessed $self->_body ? $self->_body->body : $self->_body;
123 gethostbyaddr( inet_aton( $self->address ), AF_INET ) || 'localhost'
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(@_) }
143 Catalyst::Request - provides information about the current client request
154 $req->body_parameters;
155 $req->content_encoding;
156 $req->content_length;
164 $req->query_keywords;
172 $req->query_parameters;
176 $req->captures; # previously knows as snippets
183 See also L<Catalyst>, L<Catalyst::Request::Upload>.
187 This is the Catalyst Request class, which provides an interface to data for the
188 current client request. The request object is prepared by L<Catalyst::Engine>,
189 thus hiding the details of the particular engine implementation.
195 [DEPRECATED] Returns the name of the requested action.
198 Use C<< $c->action >> instead (which returns a
199 L<Catalyst::Action|Catalyst::Action> object).
203 Returns the IP address of the client.
205 =head2 $req->arguments
207 Returns a reference to an array containing the arguments.
209 print $c->request->arguments->[0];
211 For example, if your action was
213 package MyApp::C::Foo;
219 and the URI for the request was C<http://.../foo/moose/bah>, the string C<bah>
220 would be the first and only argument.
222 Arguments get automatically URI-unescaped for you.
226 Shortcut for arguments.
230 Contains the URI base. This will always have a trailing slash. Note that the
231 URI scheme (eg., http vs. https) must be determined through heuristics;
232 depending on your server configuration, it may be incorrect. See $req->secure
235 If your application was queried with the URI
236 C<http://localhost:3000/some/path> then C<base> is C<http://localhost:3000/>.
240 Returns the message body of the request, unless Content-Type is
241 C<application/x-www-form-urlencoded> or C<multipart/form-data>.
243 =head2 $req->body_parameters
245 Returns a reference to a hash containing body (POST) parameters. Values can
246 be either a scalar or an arrayref containing scalars.
248 print $c->request->body_parameters->{field};
249 print $c->request->body_parameters->{field}->[0];
251 These are the parameters from the POST part of the request, if any.
253 =head2 $req->body_params
255 Shortcut for body_parameters.
257 =head2 $req->content_encoding
259 Shortcut for $req->headers->content_encoding.
261 =head2 $req->content_length
263 Shortcut for $req->headers->content_length.
265 =head2 $req->content_type
267 Shortcut for $req->headers->content_type.
271 A convenient method to access $req->cookies.
273 $cookie = $c->request->cookie('name');
274 @cookies = $c->request->cookie;
282 return keys %{ $self->cookies };
289 unless ( exists $self->cookies->{$name} ) {
293 return $self->cookies->{$name};
299 Returns a reference to a hash containing the cookies.
301 print $c->request->cookies->{mycookie}->value;
303 The cookies in the hash are indexed by name, and the values are L<CGI::Cookie>
308 Shortcut for $req->headers->header.
312 Returns an L<HTTP::Headers> object containing the headers for the current request.
314 print $c->request->headers->header('X-Catalyst');
316 =head2 $req->hostname
318 Returns the hostname of the client.
322 Alias for $req->body.
324 =head2 $req->query_keywords
326 Contains the keywords portion of a query string, when no '=' signs are
329 http://localhost/path?some+keywords
331 $c->request->query_keywords will contain 'some keywords'
335 This contains the matching part of a Regex action. Otherwise
336 it returns the same as 'action', except for default actions,
337 which return an empty string.
341 Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
345 Returns GET and POST parameters with a CGI.pm-compatible param method. This
346 is an alternative method for accessing parameters in $c->req->parameters.
348 $value = $c->request->param( 'foo' );
349 @values = $c->request->param( 'foo' );
350 @params = $c->request->param;
352 Like L<CGI>, and B<unlike> earlier versions of Catalyst, passing multiple
353 arguments to this method, like this:
355 $c->request->param( 'foo', 'bar', 'gorch', 'quxx' );
357 will set the parameter C<foo> to the multiple values C<bar>, C<gorch> and
358 C<quxx>. Previously this would have added C<bar> as another value to C<foo>
359 (creating it if it didn't exist before), and C<quxx> as another value for
362 B<NOTE> this is considered a legacy interface and care should be taken when
363 using it. C<< scalar $c->req->param( 'foo' ) >> will return only the first
364 C<foo> param even if multiple are present; C<< $c->req->param( 'foo' ) >> will
365 return a list of as many are present, which can have unexpected consequences
366 when writing code of the form:
370 baz => $c->req->param( 'baz' ),
373 If multiple C<baz> parameters are provided this code might corrupt data or
374 cause a hash initialization error. For a more straightforward interface see
375 C<< $c->req->parameters >>.
383 return keys %{ $self->parameters };
390 unless ( exists $self->parameters->{$param} ) {
391 return wantarray ? () : undef;
394 if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
396 ? @{ $self->parameters->{$param} }
397 : $self->parameters->{$param}->[0];
401 ? ( $self->parameters->{$param} )
402 : $self->parameters->{$param};
407 $self->parameters->{$field} = [@_];
411 =head2 $req->parameters
413 Returns a reference to a hash containing GET and POST parameters. Values can
414 be either a scalar or an arrayref containing scalars.
416 print $c->request->parameters->{field};
417 print $c->request->parameters->{field}->[0];
419 This is the combination of C<query_parameters> and C<body_parameters>.
423 Shortcut for $req->parameters.
427 Returns the path, i.e. the part of the URI after $req->base, for the current request.
429 =head2 $req->path_info
431 Alias for path, added for compatibility with L<CGI>.
436 my ( $self, @params ) = @_;
439 $self->uri->path(@params);
442 elsif ( $self->_has_path ) {
446 my $path = $self->uri->path;
447 my $location = $self->base->path;
448 $path =~ s/^(\Q$location\E)?//;
456 =head2 $req->protocol
458 Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current request.
460 =head2 $req->query_parameters
462 =head2 $req->query_params
464 Returns a reference to a hash containing query string (GET) parameters. Values can
465 be either a scalar or an arrayref containing scalars.
467 print $c->request->query_parameters->{field};
468 print $c->request->query_parameters->{field}->[0];
470 =head2 $req->read( [$maxlength] )
472 Reads a chunk of data from the request body. This method is intended to be
473 used in a while loop, reading $maxlength bytes on every call. $maxlength
474 defaults to the size of the request if not specified.
476 You have to set MyApp->config->{parse_on_demand} to use this directly.
480 Shortcut for $req->headers->referer. Returns the referring page.
484 Returns true or false, indicating whether the connection is secure
485 (https). Note that the URI scheme (eg., http vs. https) must be determined
486 through heuristics, and therefore the reliablity of $req->secure will depend
487 on your server configuration. If you are serving secure pages on the standard
488 SSL port (443) and/or setting the HTTPS environment variable, $req->secure
491 =head2 $req->captures
493 Returns a reference to an array containing captured args from chained
494 actions or regex captures.
496 my @captures = @{ $c->request->captures };
498 =head2 $req->snippets
500 C<captures> used to be called snippets. This is still available for backwards
501 compatibility, but is considered deprecated.
505 A convenient method to access $req->uploads.
507 $upload = $c->request->upload('field');
508 @uploads = $c->request->upload('field');
509 @fields = $c->request->upload;
511 for my $upload ( $c->request->upload('field') ) {
512 print $upload->filename;
521 return keys %{ $self->uploads };
528 unless ( exists $self->uploads->{$upload} ) {
529 return wantarray ? () : undef;
532 if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
534 ? @{ $self->uploads->{$upload} }
535 : $self->uploads->{$upload}->[0];
539 ? ( $self->uploads->{$upload} )
540 : $self->uploads->{$upload};
546 while ( my ( $field, $upload ) = splice( @_, 0, 2 ) ) {
548 if ( exists $self->uploads->{$field} ) {
549 for ( $self->uploads->{$field} ) {
550 $_ = [$_] unless ref($_) eq "ARRAY";
551 push( @$_, $upload );
555 $self->uploads->{$field} = $upload;
563 Returns a reference to a hash containing uploads. Values can be either a
564 L<Catalyst::Request::Upload> object, or an arrayref of
565 L<Catalyst::Request::Upload> objects.
567 my $upload = $c->request->uploads->{field};
568 my $upload = $c->request->uploads->{field}->[0];
572 Returns a URI object for the current request. Stringifies to the URI text.
574 =head2 $req->uri_with( { key => 'value' } );
576 Returns a rewritten URI object for the current request. Key/value pairs
577 passed in will override existing parameters. You can remove an existing
578 parameter by passing in an undef value. Unmodified pairs will be
584 my( $self, $args ) = @_;
586 carp( 'No arguments passed to uri_with()' ) unless $args;
588 foreach my $value ( values %$args ) {
589 next unless defined $value;
590 for ( ref $value eq 'ARRAY' ? @$value : $value ) {
592 utf8::encode( $_ ) if utf8::is_utf8($_);
596 my $uri = $self->uri->clone;
597 my %query = ( %{ $uri->query_form_hash }, %$args );
600 # remove undef values
601 map { defined $query{ $_ } ? ( $_ => $query{ $_ } ) : () } keys %query
608 Returns the currently logged in user. B<Highly deprecated>, do not call,
609 this will be removed in version 5.81.
611 =head2 $req->remote_user
613 Returns the value of the C<REMOTE_USER> environment variable.
615 =head2 $req->user_agent
617 Shortcut to $req->headers->user_agent. Returns the user agent (browser)
626 Catalyst Contributors, see Catalyst.pm
630 This library is free software. You can redistribute it and/or modify
631 it under the same terms as Perl itself.
635 __PACKAGE__->meta->make_immutable;