1Apache2::Request(3) User Contributed Perl Documentation Apache2::Request(3)
2
6 Apache2::Request - Methods for dealing with client request data
7
9 use Apache2::Request;
10 $req = Apache2::Request->new($r);
11 @foo = $req->param("foo");
12 $bar = $req->args("bar");
13
15 The Apache2::Request module provides methods for parsing GET and POST
16 parameters encoded with either application/x-www-form-urlencoded or
17 multipart/form-data. Although Apache2::Request provides a few new APIs
18 for accessing the parsed data, it remains largely backwards-compatible
19 with the original 1.X API. See the "PORTING from 1.X" section below
20 for a list of known issues.
21 This manpage documents the Apache2::Request package.
23
25 The interface is designed to mimic the CGI.pm routines for parsing
26 query parameters. The main differences are
27 * "Apache2::Request::new" takes an environment-specific object $r as
29 (second) argument. Newer versions of CGI.pm also accept this syntax
30 within modperl.
31 * The query parameters are stored in APR::Table derived objects, and
32 are therefore retrieved from the table by using case-insensitive keys.
33 * The query string is always parsed immediately, even for POST
34 requests.
35 new
37 Apache2::Request->new($r, %args)
39 Creates a new Apache2::Request object.
41 my $req = Apache2::Request->new($r, POST_MAX => "1M");
43 With mod_perl2, the environment object $r must be an
45 Apache2::RequestRec object. In that case, all methods from
46 Apache2::RequestRec are inherited. In the (default) CGI environment,
47 $r must be an APR::Pool object.
48 The following args are optional:
50 * "POST_MAX", "MAX_BODY"
52 Limit the size of POST data (in bytes).
53 * "DISABLE_UPLOADS"
55 Disable file uploads.
56 * "TEMP_DIR"
58 Sets the directory where upload files are spooled. On a *nix-like
59 that supports link(2), the TEMP_DIR should be located on the same
60 file system as the final destination file:
61 use Apache2::Upload;
63 my $req = Apache2::Request->new($r, TEMP_DIR => "/home/httpd/tmp");
64 my $upload = $req->upload('file');
65 $upload->link("/home/user/myfile");
66 For more details on "link", see Apache2::Upload.
68 * "HOOK_DATA"
70 Extra configuration info passed as the fourth argument to an upload
71 hook. See the description for the next item, "UPLOAD_HOOK".
72 * "UPLOAD_HOOK"
74 Sets up a callback to run whenever file upload data is read. This
75 can be used to provide an upload progress meter during file
76 uploads. Apache will automatically continue writing the original
77 data to $upload->fh after the hook exits.
78 my $transparent_hook = sub {
80 my ($upload, $data, $data_len, $hook_data) = @_;
81 warn "$hook_data: got $data_len bytes for " . $upload->name;
82 };
83 my $req = Apache2::Request->new($r,
85 HOOK_DATA => "Note",
86 UPLOAD_HOOK => $transparent_hook,
87 );
88 instance
90 Apache2::Request->instance($r)
92 The default (and only) behavior of Apache2::Request is to intelligently
94 cache POST data for the duration of the request. Thus there is no
95 longer the need for a separate "instance()" method as existed in
96 Apache2::Request for Apache 1.3 - all POST data is always available
97 from each and every Apache2::Request object created during the
98 request's lifetime.
99 However an "instance()" method is aliased to "new()" in this release to
101 ease the pain of porting from 1.X to 2.X.
102 param
104 $req->param()
106 $req->param($name)
107 Get the request parameters (using case-insensitive keys) by mimicing
109 the OO interface of "CGI::param".
110 # similar to CGI.pm
112 my $foo_value = $req->param('foo');
114 my @foo_values = $req->param('foo');
115 my @param_names = $req->param;
116 # the following differ slightly from CGI.pm
118 # returns ref to APR::Request::Param::Table object representing
120 # all (args + body) params
121 my $table = $req->param;
122 @table_keys = keys %$table;
123 In list context, or when invoked with no arguments as "$req->param()",
125 "param" induces libapreq2 to read and parse all remaining data in the
126 request body. However, "scalar $req->param("foo")" is lazy: libapreq2
127 will only read and parse more data if
128 1) no "foo" param appears in the query string arguments, AND
130 2) no "foo" param appears in the previously parsed POST data.
131 In this circumstance libapreq2 will read and parse additional blocks of
133 the incoming request body until either
134 1) it has found the the "foo" param, or
136 2) parsing is completed.
137 Observe that "scalar $req->param("foo")" will not raise an exception if
139 it can locate "foo" in the existing body or args tables, even if the
140 query-string parser or the body parser has failed. In all other cir‐
141 cumstances "param" will throw an Apache2::Request::Error object into $@
142 should either parser fail.
143 $req->args_status(1); # set error state for query-string parser
145 ok $req->param_status == 1;
146 $foo = $req->param("foo");
148 ok $foo == 1;
149 eval { @foo = $req->param("foo") };
150 ok $@->isa("Apache2::Request::Error");
151 undef $@;
152 eval { my $not_found = $req->param("non-existent-param") };
153 ok $@->isa("Apache2::Request::Error");
154 $req->args_status(0); # reset query-string parser state to "success"
156 Note: modifications to the "scalar $req->param()" table only affect the
158 returned table object (the underlying C apr_table_t is generated from
159 the parse data by apreq_params()). Modifications do not affect the
160 actual request data, and will not be seen by other libapreq2 applica‐
161 tions.
162 parms, params
164 The functionality of these functions is assumed by "param", so they are
166 no longer necessary. Aliases to "param" are provided in this release
167 for backwards compatibility, however they are deprecated and may be
168 removed from a future release.
169 body
171 $req->body()
173 $req->body($name)
174 Returns an APR::Request::Param::Table object containing the POST data
176 parameters of the Apache2::Request object.
177 my $body = $req->body;
179 An optional name parameter can be passed to return the POST data param‐
181 eter associated with the given name:
182 my $foo_body = $req->body("foo");
184 More generally, "body()" follows the same pattern as "param()" with
186 respect to its return values and argument list. The main difference is
187 that modifications to the "scalar $req->body()" table affect the under‐
188 lying apr_table_t attribute in apreq_request_t, so their impact will be
189 noticed by all libapreq2 applications during this request.
190 upload
192 $req->upload()
194 $req->upload($name)
195 Requires "Apache2::Upload". With no arguments, this method returns an
197 APR::Request::Param::Table object in scalar context, or the names of
198 all Apache2::Upload objects in list context.
199 An optional name parameter can be passed to return the Apache2::Upload
201 object associated with the given name:
202 my $upload = $req->upload($name);
204 More generally, "upload()" follows the same pattern as "param()" with
206 respect to its return values and argument list. The main difference is
207 that its returned values are Apache2::Upload object refs, not simple
208 scalars.
209 Note: modifications to the "scalar $req->upload()" table only affect
211 the returned table object (the underlying C apr_table_t is generated by
212 apreq_uploads()). They do not affect the actual request data, and will
213 not be seen by other libapreq2 applications.
214 args_status
216 $req->args_status()
218 Get the APR status code of the query-string parser. APR_SUCCESS on
220 success, error otherwise.
221 body_status
223 $req->body_status()
225 Get the current APR status code of the parsed POST data. APR_SUCCESS
227 when parser has completed, APR_INCOMPLETE if parser has more data to
228 parse, APR_EINIT if no post data has been parsed, error otherwise.
229 param_status
231 $req->param_status()
233 In scalar context, this returns "args_status" if there was an error
235 during the query-string parse, otherwise this returns "body_status", ie
236 $req->args_status ⎪⎪ $req->body_status
238 In list context "param_status" returns the list "(args_status,
240 body_status)".
241 parse
243 $req->parse()
245 Forces the request to be parsed immediately. In void context, this
247 will throw an APR::Request::Error should the either the query-string or
248 body parser fail. In all other contexts it will return the two parsers'
249 combined APR status code
250 $req->body_status ⎪⎪ $req->args_status
252 However "parse" should be avoided in most normal situations. For exam‐
254 ple, in a mod_perl content handler it is more efficient to write
255 sub handler {
257 my $r = shift;
258 my $req = Apache2::Request->new($r);
259 $r->discard_request_body; # efficiently parses the request body
260 my $parser_status = $req->body_status;
261 #...
263 }
264 Calling "$r->discard_request_body" outside the content handler is gen‐
266 erally a mistake, so use "$req->parse" there, but only as a last
267 resort. The Apache2::Request API is designed around a lazy-parsing
268 scheme, so calling "parse" should not affect the behavior of any other
269 methods.
270
272 If the instances of your subclass are hash references then you can
273 actually inherit from Apache2::Request as long as the Apache2::Request
274 object is stored in an attribute called "r" or "_r". (The
275 Apache2::Request class effectively does the delegation for you automag‐
276 ically, as long as it knows where to find the Apache2::Request object
277 to delegate to.) For example:
278 package MySubClass;
280 use Apache2::Request;
281 our @ISA = qw(Apache2::Request);
282 sub new {
283 my($class, @args) = @_;
284 return bless { r => Apache2::Request->new(@args) }, $class;
285 }
286
288 This is the complete list of changes to existing methods from
289 Apache2::Request 1.X. These issues need to be addressed when porting
290 1.X apps to the new 2.X API.
291 * Apache2::Upload is now a separate module. Applications requiring the
293 upload API must "use Apache2::Upload" in 2.X. This is easily addressed
294 by preloading the modules during server startup.
295 * You can no longer add (or set or delete) parameters in the "scalar
296 $req->param", "scalar $req->args" or "scalar $req->body" tables. Nor
297 can you add (or set or delete) cookies in the "scalar $req->jar" table.
298 * "instance()" is now identical to "new()", and is now deprecated. It
299 may be removed from a future 2.X release.
300 * "param" includes the functionality of "parms()" and "params()", so
301 they are now deprecated and may be removed from a future 2.X release.
302
304 APR::Request::Param, APR::Request::Error, Apache2::Upload,
305 Apache2::Cookie, APR::Table(3).
306
308 Licensed to the Apache Software Foundation (ASF) under one or more
309 contributor license agreements. See the NOTICE file distributed with
310 this work for additional information regarding copyright ownership.
311 The ASF licenses this file to You under the Apache License, Version 2.0
312 (the "License"); you may not use this file except in compliance with
313 the License. You may obtain a copy of the License at
314 http://www.apache.org/licenses/LICENSE-2.0
316 Unless required by applicable law or agreed to in writing, software
318 distributed under the License is distributed on an "AS IS" BASIS,
319 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
320 See the License for the specific language governing permissions and
321 limitations under the License.
322perl v5.8.8 2006-11-09 Apache2::Request(3)