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 env => (is => 'ro', writer => '_set_env');
18 # XXX Deprecated crap here - warn?
19 has action => (is => 'rw');
20 # XXX: Deprecated in docs ages ago (2006), deprecated with warning in 5.8000 due
21 # to confusion between Engines and Plugin::Authentication. Remove in 5.8100?
22 has user => (is => 'rw');
23 sub snippets { shift->captures(@_) }
25 has _read_position => (
26 # FIXME: work around Moose bug RT#75367
29 writer => '_set_read_position',
33 # FIXME: work around Moose bug RT#75367
38 $self->header('Content-Length') || 0;
43 has address => (is => 'rw');
44 has arguments => (is => 'rw', default => sub { [] });
45 has cookies => (is => 'ro', builder => 'prepare_cookies', lazy => 1);
50 if ( my $header = $self->header('Cookie') ) {
51 return { CGI::Simple::Cookie->parse($header) };
56 has query_keywords => (is => 'rw');
57 has match => (is => 'rw');
58 has method => (is => 'rw');
59 has protocol => (is => 'rw');
60 has query_parameters => (is => 'rw', default => sub { {} });
61 has secure => (is => 'rw', default => 0);
62 has captures => (is => 'rw', default => sub { [] });
63 has uri => (is => 'rw', predicate => 'has_uri');
64 has remote_user => (is => 'rw');
67 isa => 'HTTP::Headers',
68 handles => [qw(content_encoding content_length content_type header referer user_agent)],
69 builder => 'prepare_headers',
77 my $headers = HTTP::Headers->new();
79 for my $header (keys %{ $env }) {
80 next unless $header =~ /^(HTTP|CONTENT|COOKIE)/i;
81 (my $field = $header) =~ s/^HTTPS?_//;
83 $headers->header($field => $env->{$header});
96 predicate=>'has_io_fh',
98 builder=>'_build_io_fh');
102 return $self->env->{'psgix.io'}
103 || die "Your Server does not support psgix.io";
106 has data_handlers => ( is=>'ro', isa=>'HashRef', default=>sub { +{} } );
111 builder=>'_build_body_data');
113 sub _build_body_data {
115 my $content_type = $self->content_type;
116 my ($match) = grep { $content_type =~/$_/i }
117 keys(%{$self->data_handlers});
120 my $fh = $self->body;
122 return $self->data_handlers->{$match}->($fh, $self);
128 # Amount of data to read from input on each pass
129 our $CHUNKSIZE = 64 * 1024;
132 my ($self, $maxlength) = @_;
133 my $remaining = $self->_read_length - $self->_read_position;
134 $maxlength ||= $CHUNKSIZE;
136 # Are we done reading?
137 if ( $remaining <= 0 ) {
141 my $readlen = ( $remaining > $maxlength ) ? $maxlength : $remaining;
142 my $rc = $self->read_chunk( my $buffer, $readlen );
144 if (0 == $rc) { # Nothing more to read even though Content-Length
145 # said there should be.
148 $self->_set_read_position( $self->_read_position + $rc );
152 Catalyst::Exception->throw(
153 message => "Unknown error reading input: $!" );
159 return $self->env->{'psgi.input'}->read(@_);
162 has body_parameters => (
166 builder => 'prepare_body_parameters',
172 default => sub { {} },
178 builder => '_build_parameters',
179 clearer => '_clear_parameters',
183 # - Can we lose the before modifiers which just call prepare_body ?
184 # they are wasteful, slow us down and feel cluttery.
186 # Can we make _body an attribute, have the rest of
187 # these lazy build from there and kill all the direct hash access
188 # in Catalyst.pm and Engine.pm?
190 sub prepare_parameters {
192 $self->_clear_parameters;
193 return $self->parameters;
196 sub _build_parameters {
199 my $body_parameters = $self->body_parameters;
200 my $query_parameters = $self->query_parameters;
201 # We copy, no references
202 foreach my $name (keys %$query_parameters) {
203 my $param = $query_parameters->{$name};
204 $parameters->{$name} = ref $param eq 'ARRAY' ? [ @$param ] : $param;
207 # Merge query and body parameters
208 foreach my $name (keys %$body_parameters) {
209 my $param = $body_parameters->{$name};
210 my @values = ref $param eq 'ARRAY' ? @$param : ($param);
211 if ( my $existing = $parameters->{$name} ) {
212 unshift(@values, (ref $existing eq 'ARRAY' ? @$existing : $existing));
214 $parameters->{$name} = @values > 1 ? \@values : $values[0];
221 predicate => '_has_uploadtmp',
227 if ( my $length = $self->_read_length ) {
228 unless ( $self->_body ) {
229 my $type = $self->header('Content-Type');
230 $self->_body(HTTP::Body->new( $type, $length ));
231 $self->_body->cleanup(1); # Make extra sure!
232 $self->_body->tmpdir( $self->_uploadtmp )
233 if $self->_has_uploadtmp;
236 # Check for definedness as you could read '0'
237 while ( defined ( my $buffer = $self->read() ) ) {
238 $self->prepare_body_chunk($buffer);
241 # paranoia against wrong Content-Length header
242 my $remaining = $length - $self->_read_position;
243 if ( $remaining > 0 ) {
244 Catalyst::Exception->throw(
245 "Wrong Content-Length value: $length" );
249 # Defined but will cause all body code to be skipped
254 sub prepare_body_chunk {
255 my ( $self, $chunk ) = @_;
257 $self->_body->add($chunk);
260 sub prepare_body_parameters {
263 $self->prepare_body if ! $self->_has_body;
264 return {} unless $self->_body;
266 return $self->_body->param;
269 sub prepare_connection {
272 my $env = $self->env;
274 $self->address( $env->{REMOTE_ADDR} );
275 $self->hostname( $env->{REMOTE_HOST} )
276 if exists $env->{REMOTE_HOST};
277 $self->protocol( $env->{SERVER_PROTOCOL} );
278 $self->remote_user( $env->{REMOTE_USER} );
279 $self->method( $env->{REQUEST_METHOD} );
280 $self->secure( $env->{'psgi.url_scheme'} eq 'https' ? 1 : 0 );
283 # XXX - FIXME - method is here now, move this crap...
284 around parameters => sub {
285 my ($orig, $self, $params) = @_;
287 if ( !ref $params ) {
289 "Attempt to retrieve '$params' with req->params(), " .
290 "you probably meant to call req->param('$params')"
294 return $self->$orig($params);
305 return $self->path if $self->has_uri;
310 is => 'rw', clearer => '_clear_body', predicate => '_has_body',
312 # Eugh, ugly. Should just be able to rename accessor methods to 'body'
313 # and provide a custom reader..
316 $self->prepare_body unless ! $self->_has_body;
317 croak 'body is a reader' if scalar @_;
318 return blessed $self->_body ? $self->_body->body : $self->_body;
327 gethostbyaddr( inet_aton( $self->address ), AF_INET ) || $self->address
331 has _path => ( is => 'rw', predicate => '_has_path', clearer => '_clear_path' );
333 sub args { shift->arguments(@_) }
334 sub body_params { shift->body_parameters(@_) }
335 sub input { shift->body(@_) }
336 sub params { shift->parameters(@_) }
337 sub query_params { shift->query_parameters(@_) }
338 sub path_info { shift->path(@_) }
340 =for stopwords param params
344 Catalyst::Request - provides information about the current client request
349 $req->address eq "127.0.0.1";
354 $req->body_parameters;
355 $req->content_encoding;
356 $req->content_length;
364 $req->query_keywords;
372 $req->query_parameters;
383 See also L<Catalyst>, L<Catalyst::Request::Upload>.
387 This is the Catalyst Request class, which provides an interface to data for the
388 current client request. The request object is prepared by L<Catalyst::Engine>,
389 thus hiding the details of the particular engine implementation.
395 Returns the IP address of the client.
397 =head2 $req->arguments
399 Returns a reference to an array containing the arguments.
401 print $c->request->arguments->[0];
403 For example, if your action was
405 package MyApp::Controller::Foo;
411 and the URI for the request was C<http://.../foo/moose/bah>, the string C<bah>
412 would be the first and only argument.
414 Arguments get automatically URI-unescaped for you.
418 Shortcut for L</arguments>.
422 Contains the URI base. This will always have a trailing slash. Note that the
423 URI scheme (e.g., http vs. https) must be determined through heuristics;
424 depending on your server configuration, it may be incorrect. See $req->secure
427 If your application was queried with the URI
428 C<http://localhost:3000/some/path> then C<base> is C<http://localhost:3000/>.
432 Returns the message body of the request, as returned by L<HTTP::Body>: a string,
433 unless Content-Type is C<application/x-www-form-urlencoded>, C<text/xml>, or
434 C<multipart/form-data>, in which case a L<File::Temp> object is returned.
436 =head2 $req->body_parameters
438 Returns a reference to a hash containing body (POST) parameters. Values can
439 be either a scalar or an arrayref containing scalars.
441 print $c->request->body_parameters->{field};
442 print $c->request->body_parameters->{field}->[0];
444 These are the parameters from the POST part of the request, if any.
446 =head2 $req->body_params
448 Shortcut for body_parameters.
450 =head2 $req->content_encoding
452 Shortcut for $req->headers->content_encoding.
454 =head2 $req->content_length
456 Shortcut for $req->headers->content_length.
458 =head2 $req->content_type
460 Shortcut for $req->headers->content_type.
464 A convenient method to access $req->cookies.
466 $cookie = $c->request->cookie('name');
467 @cookies = $c->request->cookie;
475 return keys %{ $self->cookies };
482 unless ( exists $self->cookies->{$name} ) {
486 return $self->cookies->{$name};
492 Returns a reference to a hash containing the cookies.
494 print $c->request->cookies->{mycookie}->value;
496 The cookies in the hash are indexed by name, and the values are L<CGI::Simple::Cookie>
501 Shortcut for $req->headers->header.
505 Returns an L<HTTP::Headers> object containing the headers for the current request.
507 print $c->request->headers->header('X-Catalyst');
509 =head2 $req->hostname
511 Returns the hostname of the client. Use C<< $req->uri->host >> to get the hostname of the server.
515 Alias for $req->body.
517 =head2 $req->query_keywords
519 Contains the keywords portion of a query string, when no '=' signs are
522 http://localhost/path?some+keywords
524 $c->request->query_keywords will contain 'some keywords'
528 This contains the matching part of a Regex action. Otherwise
529 it returns the same as 'action', except for default actions,
530 which return an empty string.
534 Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
538 Returns GET and POST parameters with a CGI.pm-compatible param method. This
539 is an alternative method for accessing parameters in $c->req->parameters.
541 $value = $c->request->param( 'foo' );
542 @values = $c->request->param( 'foo' );
543 @params = $c->request->param;
545 Like L<CGI>, and B<unlike> earlier versions of Catalyst, passing multiple
546 arguments to this method, like this:
548 $c->request->param( 'foo', 'bar', 'gorch', 'quxx' );
550 will set the parameter C<foo> to the multiple values C<bar>, C<gorch> and
551 C<quxx>. Previously this would have added C<bar> as another value to C<foo>
552 (creating it if it didn't exist before), and C<quxx> as another value for
555 B<NOTE> this is considered a legacy interface and care should be taken when
556 using it. C<< scalar $c->req->param( 'foo' ) >> will return only the first
557 C<foo> param even if multiple are present; C<< $c->req->param( 'foo' ) >> will
558 return a list of as many are present, which can have unexpected consequences
559 when writing code of the form:
563 baz => $c->req->param( 'baz' ),
566 If multiple C<baz> parameters are provided this code might corrupt data or
567 cause a hash initialization error. For a more straightforward interface see
568 C<< $c->req->parameters >>.
576 return keys %{ $self->parameters };
583 unless ( exists $self->parameters->{$param} ) {
584 return wantarray ? () : undef;
587 if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
589 ? @{ $self->parameters->{$param} }
590 : $self->parameters->{$param}->[0];
594 ? ( $self->parameters->{$param} )
595 : $self->parameters->{$param};
600 $self->parameters->{$field} = [@_];
604 =head2 $req->parameters
606 Returns a reference to a hash containing GET and POST parameters. Values can
607 be either a scalar or an arrayref containing scalars.
609 print $c->request->parameters->{field};
610 print $c->request->parameters->{field}->[0];
612 This is the combination of C<query_parameters> and C<body_parameters>.
616 Shortcut for $req->parameters.
620 Returns the path, i.e. the part of the URI after $req->base, for the current request.
622 http://localhost/path/foo
624 $c->request->path will contain 'path/foo'
626 =head2 $req->path_info
628 Alias for path, added for compatibility with L<CGI>.
633 my ( $self, @params ) = @_;
636 $self->uri->path(@params);
639 elsif ( $self->_has_path ) {
643 my $path = $self->uri->path;
644 my $location = $self->base->path;
645 $path =~ s/^(\Q$location\E)?//;
653 =head2 $req->protocol
655 Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current request.
657 =head2 $req->query_parameters
659 =head2 $req->query_params
661 Returns a reference to a hash containing query string (GET) parameters. Values can
662 be either a scalar or an arrayref containing scalars.
664 print $c->request->query_parameters->{field};
665 print $c->request->query_parameters->{field}->[0];
667 =head2 $req->read( [$maxlength] )
669 Reads a chunk of data from the request body. This method is intended to be
670 used in a while loop, reading $maxlength bytes on every call. $maxlength
671 defaults to the size of the request if not specified.
673 =head2 $req->read_chunk(\$buff, $max)
677 You have to set MyApp->config(parse_on_demand => 1) to use this directly.
681 Shortcut for $req->headers->referer. Returns the referring page.
685 Returns true or false, indicating whether the connection is secure
686 (https). The reliability of $req->secure may depend on your server
687 configuration; Catalyst relies on PSGI to determine whether or not a
688 request is secure (Catalyst looks at psgi.url_scheme), and different
689 PSGI servers may make this determination in different ways (as by
690 directly passing along information from the server, interpreting any of
691 several HTTP headers, or using heuristics of their own).
693 =head2 $req->captures
695 Returns a reference to an array containing captured args from chained
696 actions or regex captures.
698 my @captures = @{ $c->request->captures };
702 A convenient method to access $req->uploads.
704 $upload = $c->request->upload('field');
705 @uploads = $c->request->upload('field');
706 @fields = $c->request->upload;
708 for my $upload ( $c->request->upload('field') ) {
709 print $upload->filename;
718 return keys %{ $self->uploads };
725 unless ( exists $self->uploads->{$upload} ) {
726 return wantarray ? () : undef;
729 if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
731 ? @{ $self->uploads->{$upload} }
732 : $self->uploads->{$upload}->[0];
736 ? ( $self->uploads->{$upload} )
737 : $self->uploads->{$upload};
743 while ( my ( $field, $upload ) = splice( @_, 0, 2 ) ) {
745 if ( exists $self->uploads->{$field} ) {
746 for ( $self->uploads->{$field} ) {
747 $_ = [$_] unless ref($_) eq "ARRAY";
748 push( @$_, $upload );
752 $self->uploads->{$field} = $upload;
760 Returns a reference to a hash containing uploads. Values can be either a
761 L<Catalyst::Request::Upload> object, or an arrayref of
762 L<Catalyst::Request::Upload> objects.
764 my $upload = $c->request->uploads->{field};
765 my $upload = $c->request->uploads->{field}->[0];
769 Returns a L<URI> object for the current request. Stringifies to the URI text.
771 =head2 $req->mangle_params( { key => 'value' }, $appendmode);
773 Returns a hashref of parameters stemming from the current request's params,
774 plus the ones supplied. Keys for which no current param exists will be
775 added, keys with undefined values will be removed and keys with existing
776 params will be replaced. Note that you can supply a true value as the final
777 argument to change behavior with regards to existing parameters, appending
778 values rather than replacing them.
782 # URI query params foo=1
783 my $hashref = $req->mangle_params({ foo => 2 });
784 # Result is query params of foo=2
788 # URI query params foo=1
789 my $hashref = $req->mangle_params({ foo => 2 }, 1);
790 # Result is query params of foo=1&foo=2
792 This is the code behind C<uri_with>.
797 my ($self, $args, $append) = @_;
799 carp('No arguments passed to mangle_params()') unless $args;
801 foreach my $value ( values %$args ) {
802 next unless defined $value;
803 for ( ref $value eq 'ARRAY' ? @$value : $value ) {
805 utf8::encode( $_ ) if utf8::is_utf8($_);
809 my %params = %{ $self->uri->query_form_hash };
810 foreach my $key (keys %{ $args }) {
811 my $val = $args->{$key};
814 if($append && exists($params{$key})) {
816 # This little bit of heaven handles appending a new value onto
817 # an existing one regardless if the existing value is an array
818 # or not, and regardless if the new value is an array or not
820 ref($params{$key}) eq 'ARRAY' ? @{ $params{$key} } : $params{$key},
821 ref($val) eq 'ARRAY' ? @{ $val } : $val
825 $params{$key} = $val;
829 # If the param wasn't defined then we delete it.
830 delete($params{$key});
838 =head2 $req->uri_with( { key => 'value' } );
840 Returns a rewritten URI object for the current request. Key/value pairs
841 passed in will override existing parameters. You can remove an existing
842 parameter by passing in an undef value. Unmodified pairs will be
845 You may also pass an optional second parameter that puts C<uri_with> into
848 $req->uri_with( { key => 'value' }, { mode => 'append' } );
850 See C<mangle_params> for an explanation of this behavior.
855 my( $self, $args, $behavior) = @_;
857 carp( 'No arguments passed to uri_with()' ) unless $args;
860 if((ref($behavior) eq 'HASH') && defined($behavior->{mode}) && ($behavior->{mode} eq 'append')) {
864 my $params = $self->mangle_params($args, $append);
866 my $uri = $self->uri->clone;
867 $uri->query_form($params);
872 =head2 $req->remote_user
874 Returns the value of the C<REMOTE_USER> environment variable.
876 =head2 $req->user_agent
878 Shortcut to $req->headers->user_agent. Returns the user agent (browser)
883 Returns a psgix.io bidirectional socket, if your server supports one. Used for
884 when you want to jailbreak out of PSGI and handle bidirectional client server
885 communication manually, such as when you are using cometd or websockets.
889 You should never need to call these yourself in application code,
890 however they are useful if extending Catalyst by applying a request role.
892 =head2 $self->prepare_headers()
894 Sets up the C<< $res->headers >> accessor.
896 =head2 $self->prepare_body()
898 Sets up the body using L<HTTP::Body>
900 =head2 $self->prepare_body_chunk()
902 Add a chunk to the request body.
904 =head2 $self->prepare_body_parameters()
906 Sets up parameters from body.
908 =head2 $self->prepare_cookies()
910 Parse cookies from header. Sets up a L<CGI::Simple::Cookie> object.
912 =head2 $self->prepare_connection()
914 Sets up various fields in the request like the local and remote addresses,
915 request method, hostname requested etc.
917 =head2 $self->prepare_parameters()
919 Ensures that the body has been parsed, then builds the parameters, which are
920 combined from those in the request and those in the body.
922 If parameters have already been set will clear the parameters and build them again.
931 Catalyst Contributors, see Catalyst.pm
935 This library is free software. You can redistribute it and/or modify
936 it under the same terms as Perl itself.
940 __PACKAGE__->meta->make_immutable;