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             if ( exists $self->parameters->{$field} ) {
 199                 for ( $self->parameters->{$field} ) {
 200                     $_ = [$_] unless ref($_) eq "ARRAY";
 201                     push( @$_, $value );
 202                 }
 203             }
 204             else {
 205                 $self->parameters->{$field} = $value;
 206             }
 207         }
 208     }
 209 }
 210
 211 =item $req->params
 212
 213 Shortcut for $req->parameters.
 214
 215 =item $req->parameters
 216
 217 Returns a reference to a hash containing parameters. Values can
 218 be either a scalar or a arrayref containing scalars.
 219
 220     print $c->request->parameters->{field};
 221     print $c->request->parameters->{field}->[0];
 222
 223 =item $req->path
 224
 225 Contains the path.
 226
 227     print $c->request->path;
 228
 229 =item $req->protocol
 230
 231 Contains the protocol.
 232
 233 =item $req->referer
 234
 235 Shortcut to $req->headers->referer. Referring page.
 236
 237 =item $req->secure
 238
 239 Contains a boolean whether the communciation is secure.
 240
 241 =item $req->snippets
 242
 243 Returns a reference to an array containing regex snippets.
 244
 245     my @snippets = @{ $c->request->snippets };
 246
 247 =item $req->upload
 248
 249 A convenient method to $req->uploads.
 250
 251     $upload  = $c->request->upload('field');
 252     @uploads = $c->request->upload('field');
 253     @fields  = $c->request->upload;
 254
 255     for my $upload ( $c->request->upload('field') ) {
 256         print $upload->filename;
 257     }
 258
 259 =cut
 260
 261 sub upload {
 262     my $self = shift;
 263
 264     if ( @_ == 0 ) {
 265         return keys %{ $self->uploads };
 266     }
 267
 268     if ( @_ == 1 ) {
 269
 270         my $upload = shift;
 271
 272         unless ( exists $self->uploads->{$upload} ) {
 273             return wantarray ? () : undef;
 274         }
 275
 276         if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
 277             return (wantarray)
 278               ? @{ $self->uploads->{$upload} }
 279               : $self->uploads->{$upload}->[0];
 280         }
 281         else {
 282             return (wantarray)
 283                ? ( $self->uploads->{$upload} )
 284                : $self->uploads->{$upload};
 285         }
 286     }
 287
 288     if ( @_ > 1 ) {
 289
 290         while ( my ( $field, $upload ) = splice( @_, 0, 2 ) ) {
 291
 292             if ( exists $self->uploads->{$field} ) {
 293                 for ( $self->uploads->{$field} ) {
 294                     $_ = [$_] unless ref($_) eq "ARRAY";
 295                     push( @$_, $upload );
 296                 }
 297             }
 298             else {
 299                 $self->uploads->{$field} = $upload;
 300             }
 301         }
 302     }
 303 }
 304
 305 =item $req->uploads
 306
 307 Returns a reference to a hash containing uploads. Values can be either a
 308 hashref or a arrayref containing C<Catalyst::Request::Upload> objects.
 309
 310     my $upload = $c->request->uploads->{field};
 311     my $upload = $c->request->uploads->{field}->[0];
 312
 313 =item $req->uri
 314
 315 Shortcut for C<< $req->base . $req->path >>.
 316
 317 =cut
 318
 319 sub uri {
 320     my $self = shift;
 321     my $path = shift || $self->path || '';
 322     return $self->base . $path;
 323 }
 324
 325 =item $req->user
 326
 327 Contains the user name of user if authentication check was successful.
 328
 329 =item $req->user_agent
 330
 331 Shortcut to $req->headers->user_agent. User Agent version string.
 332
 333 =back
 334
 335 =head1 AUTHOR
 336
 337 Sebastian Riedel, C<sri@cpan.org>
 338 Marcus Ramberg, C<mramberg@cpan.org>
 339
 340 =head1 COPYRIGHT
 341
 342 This program is free software, you can redistribute it and/or modify
 343 it under the same terms as Perl itself.
 344
 345 =cut
 346
 347 1;