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