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/
   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->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->content_encoding
 105
 106 Shortcut to $req->headers->content_encoding
 107
 108 =item $req->content_length
 109
 110 Shortcut to $req->headers->content_length
 111
 112 =item $req->content_type
 113
 114 Shortcut to $req->headers->content_type
 115
 116 =item $req->cookies
 117
 118 Returns a reference to a hash containing the cookies.
 119
 120     print $c->request->cookies->{mycookie}->value;
 121
 122 =item $req->header
 123
 124 Shortcut to $req->headers->header
 125
 126 =item $req->headers
 127
 128 Returns an L<HTTP::Headers> object containing the headers.
 129
 130     print $c->request->headers->header('X-Catalyst');
 131
 132 =item $req->hostname
 133
 134 Contains the hostname of the remote user.
 135
 136     print $c->request->hostname
 137
 138 =item $req->input
 139
 140 Shortcut for $req->body.
 141
 142 =item $req->match
 143
 144 This contains be the matching part of a regexp action. otherwise it
 145 returns the same as 'action'.
 146
 147     print $c->request->match;
 148
 149 =item $req->method
 150
 151 Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
 152
 153     print $c->request->method;
 154
 155 =item $req->param
 156
 157 Get request parameters with a CGI.pm like param method.
 158
 159     $value  = $c->request->param('foo');
 160     @values = $c->request->param('foo');
 161     @params = $c->request->param;
 162
 163 =cut
 164
 165 sub param {
 166     my $self = shift;
 167
 168     if ( @_ == 0 ) {
 169         return keys %{ $self->parameters };
 170     }
 171
 172     if ( @_ == 1 ) {
 173
 174         my $param = shift;
 175
 176         unless ( exists $self->parameters->{$param} ) {
 177             return wantarray ? () : undef;
 178         }
 179
 180         if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
 181             return (wantarray)
 182               ? @{ $self->parameters->{$param} }
 183               : $self->parameters->{$param}->[0];
 184         }
 185         else {
 186             return (wantarray)
 187               ? ( $self->parameters->{$param} )
 188               : $self->parameters->{$param};
 189         }
 190     }
 191
 192     if ( @_ => 2  ) {
 193
 194         while ( my ( $field, $value ) = splice( @_, 0, 2 ) ) {
 195
 196             if ( exists $self->parameters->{$field} ) {
 197                 for ( $self->parameters->{$field} ) {
 198                     $_ = [$_] unless ref($_) eq "ARRAY";
 199                     push( @$_, $value );
 200                 }
 201             }
 202             else {
 203                 $self->parameters->{$field} = $value;
 204             }
 205         }
 206     }
 207 }
 208
 209 =item $req->params
 210
 211 Shortcut for $req->parameters.
 212
 213 =item $req->parameters
 214
 215 Returns a reference to a hash containing parameters. Values can
 216 be either a scalar or a arrayref containing scalars.
 217
 218     print $c->request->parameters->{field};
 219     print $c->request->parameters->{field}->[0];
 220
 221 =item $req->path
 222
 223 Contains the path.
 224
 225     print $c->request->path;
 226
 227 =item $req->protocol
 228
 229 Contains the protocol.
 230
 231 =item $req->referer
 232
 233 Shortcut to $req->headers->referer. Referring page.
 234
 235 =item $req->secure
 236
 237 Contains a boolean whether the communciation is secure.
 238
 239 =item $req->snippets
 240
 241 Returns a reference to an array containing regex snippets.
 242
 243     my @snippets = @{ $c->request->snippets };
 244
 245 =item $req->upload
 246
 247 A convenient method to $req->uploads.
 248
 249     $upload  = $c->request->upload('field');
 250     @uploads = $c->request->upload('field');
 251     @fields  = $c->request->upload;
 252
 253     for my $upload ( $c->request->upload('field') ) {
 254         print $upload->filename;
 255     }
 256
 257 =cut
 258
 259 sub upload {
 260     my $self = shift;
 261
 262     if ( @_ == 0 ) {
 263         return keys %{ $self->uploads };
 264     }
 265
 266     if ( @_ == 1 ) {
 267
 268         my $upload = shift;
 269
 270         unless ( exists $self->uploads->{$upload} ) {
 271             return wantarray ? () : undef;
 272         }
 273
 274         if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
 275             return (wantarray)
 276               ? @{ $self->uploads->{$upload} }
 277               : $self->uploads->{$upload}->[0];
 278         }
 279         else {
 280             return (wantarray)
 281                ? ( $self->uploads->{$upload} )
 282                : $self->uploads->{$upload};
 283         }
 284     }
 285
 286     if ( @_ => 2 ) {
 287
 288         while ( my ( $field, $upload ) = splice( @_, 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
 303 =item $req->uploads
 304
 305 Returns a reference to a hash containing uploads. Values can be either a
 306 hashref or a arrayref containing C<Catalyst::Request::Upload> objects.
 307
 308     my $upload = $c->request->uploads->{field};
 309     my $upload = $c->request->uploads->{field}->[0];
 310
 311 =item $req->user_agent
 312
 313 Shortcut to $req->headers->user_agent. User Agent version string.
 314
 315 =back
 316
 317 =head1 AUTHOR
 318
 319 Sebastian Riedel, C<sri@cpan.org>
 320 Marcus Ramberg, C<mramberg@cpan.org>
 321
 322 =head1 COPYRIGHT
 323
 324 This program is free software, you can redistribute it and/or modify
 325 it under the same terms as Perl itself.
 326
 327 =cut
 328
 329 1;