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 base cookies headers hostname match method
   8       parameters path snippets uploads/
   9 );
  10
  11 *args   = \&arguments;
  12 *params = \&parameters;
  13
  14 sub content_encoding { shift->headers->content_encoding(@_) }
  15 sub content_length   { shift->headers->content_length(@_)   }
  16 sub content_type     { shift->headers->content_type(@_)     }
  17 sub header           { shift->headers->header(@_)           }
  18 sub referer          { shift->headers->referer(@_)          }
  19 sub user_agent       { shift->headers->user_agent(@_)       }
  20
  21
  22 sub _assign_values {
  23     my ( $self, $map, $values ) = @_;
  24
  25     while ( my ( $name, $value ) = splice( @{ $values }, 0, 2 ) ) {
  26
  27         if ( exists $map->{$name} ) {
  28             for ( $map->{$name} ) {
  29                 $_ = [$_] unless ref($_) eq "ARRAY";
  30                 push( @$_, $value );
  31             }
  32         }
  33         else {
  34             $map->{$name} = $value;
  35         }
  36     }
  37 }
  38
  39 =head1 NAME
  40
  41 Catalyst::Request - Catalyst Request Class
  42
  43 =head1 SYNOPSIS
  44
  45
  46     $req = $c->request;
  47     $req->action;
  48     $req->address;
  49     $req->args;
  50     $req->arguments;
  51     $req->base;
  52     $req->content_encoding;
  53     $req->content_length;
  54     $req->content_type;
  55     $req->cookies;
  56     $req->header;
  57     $req->headers;
  58     $req->hostname;
  59     $req->match;
  60     $req->method;
  61     $req->param;
  62     $req->params;
  63     $req->parameters;
  64     $req->path;
  65     $req->referer;
  66     $req->snippets;
  67     $req->upload;
  68     $req->uploads;
  69     $req->user_agent
  70
  71 See also L<Catalyst>.
  72
  73 =head1 DESCRIPTION
  74
  75 This is the Catalyst Request class, which provides a set of accessors to the
  76 request data.  The request object is prepared by the specialized Catalyst
  77 Engine module thus hiding the details of the particular engine implementation.
  78
  79
  80 =head1 METHODS
  81
  82 =over 4
  83
  84 =item $req->action
  85
  86 Contains the requested action.
  87
  88     print $c->request->action;
  89
  90 =item $req->address
  91
  92 Contains the remote address.
  93
  94     print $c->request->address
  95
  96 =item $req->args
  97
  98 Shortcut for arguments
  99
 100 =item $req->arguments
 101
 102 Returns a reference to an array containing the arguments.
 103
 104     print $c->request->arguments->[0];
 105
 106 =item $req->base
 107
 108 Contains the url base. This will always have a trailing slash.
 109
 110 =item $req->content_encoding
 111
 112 Shortcut to $req->headers->content_encoding
 113
 114 =item $req->content_length
 115
 116 Shortcut to $req->headers->content_length
 117
 118 =item $req->content_type
 119
 120 Shortcut to $req->headers->content_type
 121
 122 =item $req->cookies
 123
 124 Returns a reference to a hash containing the cookies.
 125
 126     print $c->request->cookies->{mycookie}->value;
 127
 128 =item $req->header
 129
 130 Shortcut to $req->headers->header
 131
 132 =item $req->headers
 133
 134 Returns an L<HTTP::Headers> object containing the headers.
 135
 136     print $c->request->headers->header('X-Catalyst');
 137
 138 =item $req->hostname
 139
 140 Contains the hostname of the remote user.
 141
 142     print $c->request->hostname
 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     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 =item $req->params
 193
 194 Shortcut for $req->parameters.
 195
 196 =item $req->parameters
 197
 198 Returns a reference to a hash containing parameters. Values can
 199 be either a scalar or a arrayref containing scalars.
 200
 201     print $c->request->parameters->{field};
 202     print $c->request->parameters->{field}->[0];
 203
 204 =item $req->path
 205
 206 Contains the path.
 207
 208     print $c->request->path;
 209
 210 =item $req->referer
 211
 212 Shortcut to $req->headers->referer. Referring page.
 213
 214 =item $req->snippets
 215
 216 Returns a reference to an array containing regex snippets.
 217
 218     my @snippets = @{ $c->request->snippets };
 219
 220 =item $req->upload
 221
 222 A convenient method to $req->uploads.
 223
 224     $upload  = $c->request->upload('field');
 225     @uploads = $c->request->upload('field');
 226     @fields  = $c->request->upload;
 227
 228     for my $upload ( $c->request->upload('field') ) {
 229         print $upload->{filename};
 230     }
 231
 232 =cut
 233
 234 sub upload {
 235     my $self = shift;
 236
 237     if ( @_ == 0 ) {
 238         return keys %{ $self->uploads };
 239     }
 240
 241     my $upload = shift;
 242
 243     unless ( exists $self->uploads->{$upload} ) {
 244         return wantarray ? () : undef;
 245     }
 246
 247     if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
 248         return (wantarray)
 249           ? @{ $self->uploads->{$upload} }
 250           : $self->uploads->{$upload}->[0];
 251     }
 252     else {
 253         return (wantarray)
 254           ? ( $self->uploads->{$upload} )
 255           : $self->uploads->{$upload};
 256     }
 257 }
 258
 259 =item $req->uploads
 260
 261 Returns a reference to a hash containing uploads. Values can
 262 be either a hashref or a arrayref containing hashrefs.
 263
 264     my $upload = $c->request->uploads->{field};
 265     my $upload = $c->request->uploads->{field}->[0];
 266
 267 The upload hashref contains the following keys:
 268
 269 =over 4
 270
 271 =item * fh
 272
 273 Filehandle.
 274
 275 =item * filename
 276
 277 Client supplied filename.
 278
 279 =item * size
 280
 281 Size of the file in bytes.
 282
 283 =item * tempname
 284
 285 Path to the temporary spool file.
 286
 287 =item * type
 288
 289 Client supplied Content-Type.
 290
 291 =back
 292
 293 =item $req->user_agent
 294
 295 Shortcut to $req->headers->user_agent. User Agent version string.
 296
 297 =back
 298
 299 =head1 AUTHOR
 300
 301 Sebastian Riedel, C<sri@cpan.org>
 302 Marcus Ramberg, C<mramberg@cpan.org>
 303
 304 =head1 COPYRIGHT
 305
 306 This program is free software, you can redistribute it and/or modify
 307 it under the same terms as Perl itself.
 308
 309 =cut
 310
 311 1;