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