lib/Catalyst/Request.pm

   1 package Catalyst::Request;
   2
   3 use strict;
   4 use base 'Class::Accessor::Fast';
   5
   6 __PACKAGE__->mk_accessors(
   7     qw/action address arguments base cookies headers hostname match method
   8       parameters path snippets uploads/
   9 );
  10
  11 *args   = \&arguments;
  12 *params = \&parameters;
  13
  14 sub content_encoding { shift->headers->content_encoding(@_) }
  15 sub content_length   { shift->headers->content_length(@_)   }
  16 sub content_type     { shift->headers->content_type(@_)     }
  17 sub header           { shift->headers->header(@_)           }
  18 sub referer          { shift->headers->referer(@_)          }
  19 sub user_agent       { shift->headers->user_agent(@_)       }
  20
  21 sub _assign_values {
  22     my ( $self, $map, $values ) = @_;
  23
  24     while ( my ( $name, $value ) = splice( @{$values}, 0, 2 ) ) {
  25
  26         if ( exists $map->{$name} ) {
  27             for ( $map->{$name} ) {
  28                 $_ = [$_] unless ref($_) eq "ARRAY";
  29                 push( @$_, $value );
  30             }
  31         }
  32         else {
  33             $map->{$name} = $value;
  34         }
  35     }
  36 }
  37
  38 =head1 NAME
  39
  40 Catalyst::Request - Catalyst Request Class
  41
  42 =head1 SYNOPSIS
  43
  44
  45     $req = $c->request;
  46     $req->action;
  47     $req->address;
  48     $req->args;
  49     $req->arguments;
  50     $req->base;
  51     $req->content_encoding;
  52     $req->content_length;
  53     $req->content_type;
  54     $req->cookies;
  55     $req->header;
  56     $req->headers;
  57     $req->hostname;
  58     $req->match;
  59     $req->method;
  60     $req->param;
  61     $req->params;
  62     $req->parameters;
  63     $req->path;
  64     $req->referer;
  65     $req->snippets;
  66     $req->upload;
  67     $req->uploads;
  68     $req->user_agent
  69
  70 See also L<Catalyst>.
  71
  72 =head1 DESCRIPTION
  73
  74 This is the Catalyst Request class, which provides a set of accessors to the
  75 request data.  The request object is prepared by the specialized Catalyst
  76 Engine module thus hiding the details of the particular engine implementation.
  77
  78
  79 =head1 METHODS
  80
  81 =over 4
  82
  83 =item $req->action
  84
  85 Contains the requested action.
  86
  87     print $c->request->action;
  88
  89 =item $req->address
  90
  91 Contains the remote address.
  92
  93     print $c->request->address
  94
  95 =item $req->args
  96
  97 Shortcut for arguments
  98
  99 =item $req->arguments
 100
 101 Returns a reference to an array containing the arguments.
 102
 103     print $c->request->arguments->[0];
 104
 105 =item $req->base
 106
 107 Contains the url base. This will always have a trailing slash.
 108
 109 =item $req->content_encoding
 110
 111 Shortcut to $req->headers->content_encoding
 112
 113 =item $req->content_length
 114
 115 Shortcut to $req->headers->content_length
 116
 117 =item $req->content_type
 118
 119 Shortcut to $req->headers->content_type
 120
 121 =item $req->cookies
 122
 123 Returns a reference to a hash containing the cookies.
 124
 125     print $c->request->cookies->{mycookie}->value;
 126
 127 =item $req->header
 128
 129 Shortcut to $req->headers->header
 130
 131 =item $req->headers
 132
 133 Returns an L<HTTP::Headers> object containing the headers.
 134
 135     print $c->request->headers->header('X-Catalyst');
 136
 137 =item $req->hostname
 138
 139 Contains the hostname of the remote user.
 140
 141     print $c->request->hostname
 142
 143 =item $req->match
 144
 145 This contains be the matching part of a regexp action. otherwise it
 146 returns the same as 'action'.
 147
 148     print $c->request->match;
 149
 150 =item $req->method
 151
 152 Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
 153
 154     print $c->request->method;
 155
 156 =item $req->param
 157
 158 Get request parameters with a CGI.pm like param method.
 159
 160     $value  = $c->request->param('foo');
 161     @values = $c->request->param('foo');
 162     @params = $c->request->param;
 163
 164 =cut
 165
 166 sub param {
 167     my $self = shift;
 168
 169     if ( @_ == 0 ) {
 170         return keys %{ $self->parameters };
 171     }
 172
 173     my $param = shift;
 174
 175     unless ( exists $self->parameters->{$param} ) {
 176         return wantarray ? () : undef;
 177     }
 178
 179     if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
 180         return (wantarray)
 181           ? @{ $self->parameters->{$param} }
 182           : $self->parameters->{$param}->[0];
 183     }
 184     else {
 185         return (wantarray)
 186           ? ( $self->parameters->{$param} )
 187           : $self->parameters->{$param};
 188     }
 189 }
 190
 191 =item $req->params
 192
 193 Shortcut for $req->parameters.
 194
 195 =item $req->parameters
 196
 197 Returns a reference to a hash containing parameters. Values can
 198 be either a scalar or a arrayref containing scalars.
 199
 200     print $c->request->parameters->{field};
 201     print $c->request->parameters->{field}->[0];
 202
 203 =item $req->path
 204
 205 Contains the path.
 206
 207     print $c->request->path;
 208
 209 =item $req->referer
 210
 211 Shortcut to $req->headers->referer. Referring page.
 212
 213 =item $req->snippets
 214
 215 Returns a reference to an array containing regex snippets.
 216
 217     my @snippets = @{ $c->request->snippets };
 218
 219 =item $req->upload
 220
 221 A convenient method to $req->uploads.
 222
 223     $upload  = $c->request->upload('field');
 224     @uploads = $c->request->upload('field');
 225     @fields  = $c->request->upload;
 226
 227     for my $upload ( $c->request->upload('field') ) {
 228         print $upload->filename;
 229     }
 230
 231 =cut
 232
 233 sub upload {
 234     my $self = shift;
 235
 236     if ( @_ == 0 ) {
 237         return keys %{ $self->uploads };
 238     }
 239
 240     my $upload = shift;
 241
 242     unless ( exists $self->uploads->{$upload} ) {
 243         return wantarray ? () : undef;
 244     }
 245
 246     if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
 247         return (wantarray)
 248           ? @{ $self->uploads->{$upload} }
 249           : $self->uploads->{$upload}->[0];
 250     }
 251     else {
 252         return (wantarray)
 253           ? ( $self->uploads->{$upload} )
 254           : $self->uploads->{$upload};
 255     }
 256 }
 257
 258 =item $req->uploads
 259
 260 Returns a reference to a hash containing uploads. Values can be either a
 261 hashref or a arrayref containing C<Catalyst::Request::Upload> objects.
 262
 263     my $upload = $c->request->uploads->{field};
 264     my $upload = $c->request->uploads->{field}->[0];
 265
 266 =item $req->user_agent
 267
 268 Shortcut to $req->headers->user_agent. User Agent version string.
 269
 270 =back
 271
 272 =head1 AUTHOR
 273
 274 Sebastian Riedel, C<sri@cpan.org>
 275 Marcus Ramberg, C<mramberg@cpan.org>
 276
 277 =head1 COPYRIGHT
 278
 279 This program is free software, you can redistribute it and/or modify
 280 it under the same terms as Perl itself.
 281
 282 =cut
 283
 284 1;