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