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 input hostname match
   8       method 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 sub _assign_values {
  22     my ( $self, $map, $values ) = @_;
  23
  24     while ( my ( $name, $value ) = splice( @{$values}, 0, 2 ) ) {
  25
  26         if ( exists $map->{$name} ) {
  27             for ( $map->{$name} ) {
  28                 $_ = [$_] unless ref($_) eq "ARRAY";
  29                 push( @$_, $value );
  30             }
  31         }
  32         else {
  33             $map->{$name} = $value;
  34         }
  35     }
  36 }
  37
  38 =head1 NAME
  39
  40 Catalyst::Request - Catalyst Request Class
  41
  42 =head1 SYNOPSIS
  43
  44
  45     $req = $c->request;
  46     $req->action;
  47     $req->address;
  48     $req->args;
  49     $req->arguments;
  50     $req->base;
  51     $req->content_encoding;
  52     $req->content_length;
  53     $req->content_type;
  54     $req->cookies;
  55     $req->header;
  56     $req->headers;
  57     $req->hostname;
  58     $req->input;
  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->input
 145
 146 Contains the message body of the request unless Content-Type is
 147 C<application/x-www-form-urlencoded> or C<multipart/form-data>.
 148
 149     print $c->request->input
 150
 151 =item $req->match
 152
 153 This contains be the matching part of a regexp action. otherwise it
 154 returns the same as 'action'.
 155
 156     print $c->request->match;
 157
 158 =item $req->method
 159
 160 Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
 161
 162     print $c->request->method;
 163
 164 =item $req->param
 165
 166 Get request parameters with a CGI.pm like param method.
 167
 168     $value  = $c->request->param('foo');
 169     @values = $c->request->param('foo');
 170     @params = $c->request->param;
 171
 172 =cut
 173
 174 sub param {
 175     my $self = shift;
 176
 177     if ( @_ == 0 ) {
 178         return keys %{ $self->parameters };
 179     }
 180
 181     my $param = shift;
 182
 183     unless ( exists $self->parameters->{$param} ) {
 184         return wantarray ? () : undef;
 185     }
 186
 187     if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
 188         return (wantarray)
 189           ? @{ $self->parameters->{$param} }
 190           : $self->parameters->{$param}->[0];
 191     }
 192     else {
 193         return (wantarray)
 194           ? ( $self->parameters->{$param} )
 195           : $self->parameters->{$param};
 196     }
 197 }
 198
 199 =item $req->params
 200
 201 Shortcut for $req->parameters.
 202
 203 =item $req->parameters
 204
 205 Returns a reference to a hash containing parameters. Values can
 206 be either a scalar or a arrayref containing scalars.
 207
 208     print $c->request->parameters->{field};
 209     print $c->request->parameters->{field}->[0];
 210
 211 =item $req->path
 212
 213 Contains the path.
 214
 215     print $c->request->path;
 216
 217 =item $req->referer
 218
 219 Shortcut to $req->headers->referer. Referring page.
 220
 221 =item $req->snippets
 222
 223 Returns a reference to an array containing regex snippets.
 224
 225     my @snippets = @{ $c->request->snippets };
 226
 227 =item $req->upload
 228
 229 A convenient method to $req->uploads.
 230
 231     $upload  = $c->request->upload('field');
 232     @uploads = $c->request->upload('field');
 233     @fields  = $c->request->upload;
 234
 235     for my $upload ( $c->request->upload('field') ) {
 236         print $upload->filename;
 237     }
 238
 239 =cut
 240
 241 sub upload {
 242     my $self = shift;
 243
 244     if ( @_ == 0 ) {
 245         return keys %{ $self->uploads };
 246     }
 247
 248     my $upload = shift;
 249
 250     unless ( exists $self->uploads->{$upload} ) {
 251         return wantarray ? () : undef;
 252     }
 253
 254     if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
 255         return (wantarray)
 256           ? @{ $self->uploads->{$upload} }
 257           : $self->uploads->{$upload}->[0];
 258     }
 259     else {
 260         return (wantarray)
 261           ? ( $self->uploads->{$upload} )
 262           : $self->uploads->{$upload};
 263     }
 264 }
 265
 266 =item $req->uploads
 267
 268 Returns a reference to a hash containing uploads. Values can be either a
 269 hashref or a arrayref containing C<Catalyst::Request::Upload> objects.
 270
 271     my $upload = $c->request->uploads->{field};
 272     my $upload = $c->request->uploads->{field}->[0];
 273
 274 =item $req->user_agent
 275
 276 Shortcut to $req->headers->user_agent. User Agent version string.
 277
 278 =back
 279
 280 =head1 AUTHOR
 281
 282 Sebastian Riedel, C<sri@cpan.org>
 283 Marcus Ramberg, C<mramberg@cpan.org>
 284
 285 =head1 COPYRIGHT
 286
 287 This program is free software, you can redistribute it and/or modify
 288 it under the same terms as Perl itself.
 289
 290 =cut
 291
 292 1;