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
29 object $r as (second) argument. Newer versions of CGI.pm
30 also accept
31 this syntax within modperl.
32 • The query parameters are stored in APR::Table derived objects, and
34 are therefore retrieved from the table by using case-
35 insensitive keys.
36 • The query string is always parsed immediately, even for POST
38 requests.
39 new
41 Apache2::Request->new($r, %args)
42 Creates a new Apache2::Request object.
44 my $req = Apache2::Request->new($r, POST_MAX => "1M");
46 With mod_perl2, the environment object $r must be an
48 Apache2::RequestRec object. In that case, all methods from
49 Apache2::RequestRec are inherited. In the (default) CGI environment,
50 $r must be an APR::Pool object.
51 The following args are optional:
53 • "POST_MAX", "MAX_BODY"
55 Limit the size of POST data (in bytes).
57 • "DISABLE_UPLOADS"
59 Disable file uploads.
61 • "TEMP_DIR"
63 Sets the directory where upload files are spooled. On a *nix-like
65 that supports link(2), the TEMP_DIR should be located on the same
66 file system as the final destination file:
67 use Apache2::Upload;
69 my $req = Apache2::Request->new($r, TEMP_DIR => "/home/httpd/tmp");
70 my $upload = $req->upload('file');
71 $upload->link("/home/user/myfile");
72 For more details on "link", see Apache2::Upload.
74 • "HOOK_DATA"
76 Extra configuration info passed as the fourth argument to an upload
78 hook. See the description for the next item, "UPLOAD_HOOK".
79 • "UPLOAD_HOOK"
81 Sets up a callback to run whenever file upload data is read. This
83 can be used to provide an upload progress meter during file
84 uploads. Apache will automatically continue writing the original
85 data to $upload->fh after the hook exits.
86 my $transparent_hook = sub {
88 my ($upload, $data, $data_len, $hook_data) = @_;
89 warn "$hook_data: got $data_len bytes for " . $upload->name;
90 };
91 my $req = Apache2::Request->new($r,
93 HOOK_DATA => "Note",
94 UPLOAD_HOOK => $transparent_hook,
95 );
96 instance
98 Apache2::Request->instance($r)
99 The default (and only) behavior of Apache2::Request is to intelligently
101 cache POST data for the duration of the request. Thus there is no
102 longer the need for a separate instance() method as existed in
103 Apache2::Request for Apache 1.3 - all POST data is always available
104 from each and every Apache2::Request object created during the
105 request's lifetime.
106 However an instance() method is aliased to new() in this release to
108 ease the pain of porting from 1.X to 2.X.
109 param
111 $req->param()
112 $req->param($name)
113 Get the request parameters (using case-insensitive keys) by mimicing
115 the OO interface of "CGI::param".
116 # similar to CGI.pm
118 my $foo_value = $req->param('foo');
120 my @foo_values = $req->param('foo');
121 my @param_names = $req->param;
122 # the following differ slightly from CGI.pm
124 # returns ref to APR::Request::Param::Table object representing
126 # all (args + body) params
127 my $table = $req->param;
128 @table_keys = keys %$table;
129 In list context, or when invoked with no arguments as "$req->param()",
131 "param" induces libapreq2 to read and parse all remaining data in the
132 request body. However, "scalar $req->param("foo")" is lazy: libapreq2
133 will only read and parse more data if
134 1) no "foo" param appears in the query string arguments, AND
136 2) no "foo" param appears in the previously parsed POST data.
137 In this circumstance libapreq2 will read and parse additional blocks of
139 the incoming request body until either
140 1) it has found the the "foo" param, or
142 2) parsing is completed.
143 Observe that "scalar $req->param("foo")" will not raise an exception if
145 it can locate "foo" in the existing body or args tables, even if the
146 query-string parser or the body parser has failed. In all other
147 circumstances "param" will throw an Apache2::Request::Error object into
148 $@ should either parser fail.
149 $req->args_status(1); # set error state for query-string parser
151 ok $req->param_status == 1;
152 $foo = $req->param("foo");
154 ok $foo == 1;
155 eval { @foo = $req->param("foo") };
156 ok $@->isa("Apache2::Request::Error");
157 undef $@;
158 eval { my $not_found = $req->param("non-existent-param") };
159 ok $@->isa("Apache2::Request::Error");
160 $req->args_status(0); # reset query-string parser state to "success"
162 Note: modifications to the "scalar $req->param()" table only affect the
164 returned table object (the underlying C apr_table_t is generated from
165 the parse data by apreq_params()). Modifications do not affect the
166 actual request data, and will not be seen by other libapreq2
167 applications.
168 parms, params
170 The functionality of these functions is assumed by "param", so they are
171 no longer necessary. Aliases to "param" are provided in this release
172 for backwards compatibility, however they are deprecated and may be
173 removed from a future release.
174 body
176 $req->body()
177 $req->body($name)
178 Returns an APR::Request::Param::Table object containing the POST data
180 parameters of the Apache2::Request object.
181 my $body = $req->body;
183 An optional name parameter can be passed to return the POST data
185 parameter associated with the given name:
186 my $foo_body = $req->body("foo");
188 More generally, body() follows the same pattern as param() with respect
190 to its return values and argument list. The main difference is that
191 modifications to the "scalar $req->body()" table affect the underlying
192 apr_table_t attribute in apreq_request_t, so their impact will be
193 noticed by all libapreq2 applications during this request.
194 upload
196 $req->upload()
197 $req->upload($name)
198 Requires "Apache2::Upload". With no arguments, this method returns an
200 APR::Request::Param::Table object in scalar context, or the names of
201 all Apache2::Upload objects in list context.
202 An optional name parameter can be passed to return the Apache2::Upload
204 object associated with the given name:
205 my $upload = $req->upload($name);
207 More generally, upload() follows the same pattern as param() with
209 respect to its return values and argument list. The main difference is
210 that its returned values are Apache2::Upload object refs, not simple
211 scalars.
212 Note: modifications to the "scalar $req->upload()" table only affect
214 the returned table object (the underlying C apr_table_t is generated by
215 apreq_uploads()). They do not affect the actual request data, and will
216 not be seen by other libapreq2 applications.
217 args_status
219 $req->args_status()
220 Get the APR status code of the query-string parser. APR_SUCCESS on
222 success, error otherwise.
223 body_status
225 $req->body_status()
226 Get the current APR status code of the parsed POST data. APR_SUCCESS
228 when parser has completed, APR_INCOMPLETE if parser has more data to
229 parse, APR_EINIT if no post data has been parsed, error otherwise.
230 param_status
232 $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()
244 Forces the request to be parsed immediately. In void context, this
246 will throw an APR::Request::Error should the either the query-string or
247 body parser fail. In all other contexts it will return the two parsers'
248 combined APR status code
249 $req->body_status || $req->args_status
251 However "parse" should be avoided in most normal situations. For
253 example, in a mod_perl content handler it is more efficient to write
254 sub handler {
256 my $r = shift;
257 my $req = Apache2::Request->new($r);
258 $r->discard_request_body; # efficiently parses the request body
259 my $parser_status = $req->body_status;
260 #...
262 }
263 Calling "$r->discard_request_body" outside the content handler is
265 generally a mistake, so use "$req->parse" there, but only as a last
266 resort. The Apache2::Request API is designed around a lazy-parsing
267 scheme, so calling "parse" should not affect the behavior of any other
268 methods.
269
271 If the instances of your subclass are hash references then you can
272 actually inherit from Apache2::Request as long as the Apache2::Request
273 object is stored in an attribute called "r" or "_r". (The
274 Apache2::Request class effectively does the delegation for you
275 automagically, as long as it knows where to find the Apache2::Request
276 object to delegate to.) For example:
277 package MySubClass;
279 use Apache2::Request;
280 our @ISA = qw(Apache2::Request);
281 sub new {
282 my($class, @args) = @_;
283 return bless { r => Apache2::Request->new(@args) }, $class;
284 }
285
287 This is the complete list of changes to existing methods from
288 Apache2::Request 1.X. These issues need to be addressed when porting
289 1.X apps to the new 2.X API.
290 • Apache2::Upload is now a separate module. Applications
292 requiring the upload API must "use Apache2::Upload" in 2.X.
293 This is easily addressed by preloading the modules during
294 server startup.
295 • You can no longer add (or set or delete) parameters in the
297 "scalar $req->param", "scalar $req->args" or
298 "scalar $req->body" tables. Nor can you add (or set or
299 delete)
300 cookies in the "scalar $req->jar" table.
301 • instance() is now identical to new(), and is now deprecated. It
303 may be removed from a future 2.X release.
304 • "param" includes the functionality of parms() and params(), so
306 they are now deprecated and may be removed from a future
307 2.X release.
308 • "param" called in a list context no longer returns a unique list of
310 paramaters. The returned list contains multiple instances
311 of the
312 parameter name for multivalued fields.
313
315 APR::Request::Param, APR::Request::Error, Apache2::Upload,
316 Apache2::Cookie, APR::Table(3).
317
319 Licensed to the Apache Software Foundation (ASF) under one or more
320 contributor license agreements. See the NOTICE file distributed with
321 this work for additional information regarding copyright ownership.
322 The ASF licenses this file to You under the Apache License, Version 2.0
323 (the "License"); you may not use this file except in compliance with
324 the License. You may obtain a copy of the License at
325 http://www.apache.org/licenses/LICENSE-2.0
327 Unless required by applicable law or agreed to in writing, software
329 distributed under the License is distributed on an "AS IS" BASIS,
330 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
331 See the License for the specific language governing permissions and
332 limitations under the License.
333perl v5.38.0 2023-07-20 Apache2::Request(3)