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