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