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