Apache2::RequestUtil(3pm)

1docs::api::Apache2::ReqUuseesrtUCtoinlt(r3i)buted Perl Ddooccusm:e:natpait:i:oAnpache2::RequestUtil(3)
2
3
4

NAME

6       Apache2::RequestUtil - Perl API for Apache request record utils
7

Synopsis

9         use Apache2::RequestUtil ();
10
11         # add httpd config dynamically
12         $r->add_config(['require valid-user']);
13
14         # dump the request object as a string
15         print $r->as_string();
16
17         # default content_type
18         $content_type = $r->default_type();
19
20         # get PerlSetVar/PerlAddVar values
21         @values = $r->dir_config->get($key);
22
23         # get server docroot
24         $docroot = $r->document_root();
25
26         # set server docroot
27         $r->document_root($new_root);
28
29         # what are the registered perl handlers for a given phase
30         my @handlers = @{ $r->get_handlers('PerlResponseHandler') || [] };
31
32         # push a new handler for a given phase
33         $r->push_handlers(PerlCleanupHandler => \&handler);
34
35         # set handlers for a given phase (resetting previous values)
36         $r->set_handlers(PerlCleanupHandler => []);
37
38         # what's the request body limit
39         $limit = $r->get_limit_req_body();
40
41         # server and port names
42         $server = $r->get_server_name();
43         $port   = $r->get_server_port();
44
45         # what string Apache is going to send for a given status code
46         $status_line = Apache2::RequestUtil::get_status_line(404);
47
48         # are we in the main request?
49         $is_initial = $r->is_initial_req();
50
51         # directory level PerlOptions flags lookup
52         $r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');
53
54         # current <Location> value
55         $location = $r->location();
56
57         # merge a <Location> container in a request object
58         $r->location_merge($location);
59
60         # create a new Apache2::RequestRec object
61         $r = Apache2::RequestRec->new($c);
62
63         # tell the client not to cache the response
64         $r->no_cache($boolean);
65
66         # share perl objects like $r->notes
67         $r->pnotes($key => [$obj1, $obj2]);
68
69         # get HTML signature
70         $sig = $r->psignature($prefix);
71
72         # get the global request object (requires PerlOptions +GlobalRequest)
73         $r = Apache2::RequestUtil->request;
74
75         # insert auth credentials into the request as if the client did that
76         $r->set_basic_credentials($username, $password);
77
78         # slurp the contents of $r->filename
79         my $content = ${ $r->slurp_filename() };
80
81         # terminate the current child after this request
82         $r->child_terminate();
83

Description

85       "Apache2::RequestUtil" provides the Apache request object utilities
86       API.
87

API

89   "add_config"
90       Dynamically add Apache configuration at request processing runtime:
91
92         $r->add_config($lines);
93         $r->add_config($lines, $override);
94         $r->add_config($lines, $override, $path);
95         $r->add_config($lines, $override, $path, $override_opts);
96
97       Configuration directives are processed as if given in a "<Location>"
98       block.
99
100       obj: $r ( "Apache2::RequestRec object" )
101       arg1: $lines (ARRAY ref)
102           An ARRAY reference containing configuration lines per element,
103           without the new line terminators.
104
105       opt arg2: $override ( "Apache2::Const override constant" )
106           Which allow-override bits are set
107
108           Default value is: "Apache2::Const::OR_AUTHCFG"
109
110       opt arg3: $path ( string )
111           Set the "Apache2::CmdParms object" "path" component.  This is the
112           path of the "<Location>" block. Some directives need this, for
113           example "ProxyPassReverse".
114
115           If an empty string is passed a "NULL" pointer is passed further at
116           C-level.  This is necessary to make something like this work:
117
118             $r->add_config( [
119                              '<Directory />',
120                              'AllowOverride Options AuthConfig',
121                              '</Directory>',
122                             ], ~0, '' );
123
124           Note: "AllowOverride" is valid only in directory context.
125
126           Caution: Some directives need a non-empty path otherwise they cause
127           segfaults. Thus, use the empty path with caution.
128
129           Default value is: "/"
130
131       opt arg4: $override_opts ( "Apache2::Const options constant" )
132           Apache limits the applicable directives in certain situations with
133           "AllowOverride". With Apache 2.2 comes the possibility to enable or
134           disable single options, for example
135
136             AllowOverride AuthConfig Options=ExecCGI,Indexes
137
138           Internally, this directive is parsed into 2 bit fields that are
139           represented by the $override and $override_opts parameters to
140           "add_config".  The above example is parsed into an $override with 2
141           bits set, one for "AuthConfig" the other for "Options" and an
142           $override_opts with 2 bits set for ExecCGI and Indexes.
143
144           When applying other directives, for example "AuthType" or "Options"
145           the appropriate bits in $override must be set. For the "Options"
146           directive additionally $override_opts bits must be set.
147
148           The $override and $override_opts parameters to "add_config" are
149           valid while applying $lines.
150
151           $override_opts is new in Apache 2.2. The mod_perl implementation
152           for Apache 2.0 lets you pass the parameter but ignores it.
153
154           Default for $override_opts is: "Apache2::Const::OPT_UNSET" |
155           "Apache2::Const::OPT_ALL" | "Apache2::Const::OPT_INCNOEXEC" |
156           "Apache2::Const::OPT_SYM_OWNER" | "Apache2::Const::OPT_MULTI"
157
158           That means, all options are allowed.
159
160       ret: no return value
161       since: 2.0.00, $path and $override_opts since 2.0.3
162
163       See also: "$s->add_config"
164
165       For example:
166
167         use Apache2::RequestUtil ();
168         use Apache2::Access ();
169
170         $r->add_config(['require valid-user']);
171
172         # this regards the current AllowOverride setting
173         $r->add_config(['AuthName secret',
174                         'AuthType Basic',
175                         'Options ExecCGI'],
176                        $r->allow_override, $path, $r->allow_override_opts);
177
178   "as_string"
179       Dump the request object as a string
180
181         $dump = $r->as_string();
182
183       obj: $r ( "Apache2::RequestRec object" )
184       ret: $dump ( string )
185       since: 2.0.00
186
187       Dumps various request and response headers (mainly useful for
188       debugging)
189
190   "child_terminate"
191       Terminate the current worker process as soon as the current request is
192       over
193
194         $r->child_terminate();
195
196       obj: $r ( "Apache2::RequestRec object" )
197       ret: no return value
198       since: 2.0.00
199
200       This method is not supported in threaded MPMs
201
202   "default_type"
203       Retrieve the value of the DefaultType directive for the current
204       request. If not set "text/plain" is returned.
205
206         $content_type = $r->default_type();
207
208       obj: $r ( "Apache2::RequestRec object" )
209           The current request
210
211       ret: $content_type ( string )
212           The default type
213
214       since: 2.0.00
215
216   "dir_config"
217       "$r->dir_config()" provides an interface for the per-directory variable
218       specified by the "PerlSetVar" and "PerlAddVar" directives, and also can
219       be manipulated via the "APR::Table" methods.
220
221         $table  = $r->dir_config();
222         $value  = $r->dir_config($key);
223         @values = $r->dir_config->get($key);
224         $r->dir_config($key, $val);
225
226       obj: $r ( "Apache2::RequestRec object" )
227       opt arg2: $key ( string )
228           Key string
229
230       opt arg3: $val ( string )
231           Value string
232
233       ret: ...
234           Depends on the passed arguments, see further discussion
235
236       since: 2.0.00
237
238       The keys are case-insensitive.
239
240         $apr_table = $r->dir_config();
241
242       dir_config() called in a scalar context without the $key argument
243       returns a HASH reference blessed into the "APR::Table" class. This
244       object can be manipulated via the "APR::Table" methods. For available
245       methods see the "APR::Table" manpage.
246
247         $value = $r->dir_config($key);
248
249       If the $key argument is passed in the scalar context only a single
250       value will be returned. Since the table preserves the insertion order,
251       if there is more than one value for the same key, the oldest value
252       assosiated with the desired key is returned. Calling in the scalar
253       context is also much faster, as it'll stop searching the table as soon
254       as the first match happens.
255
256         @values = $r->dir_config->get($key);
257
258       To receive a list of values you must use "get()" method from the
259       "APR::Table" class.
260
261         $r->dir_config($key => $val);
262
263       If the $key and the $val arguments are used, the set() operation will
264       happen: all existing values associated with the key $key (and the key
265       itself) will be deleted and $value will be placed instead.
266
267         $r->dir_config($key => undef);
268
269       If $val is undef the unset() operation will happen: all existing values
270       associated with the key $key (and the key itself) will be deleted.
271
272   "document_root"
273       Retrieve the document root for this server
274
275         $docroot = $r->document_root();
276         $docroot = $r->document_root($new_root);
277
278       obj: $r ( "Apache2::RequestRec object" )
279           The current request
280
281       opt arg1: $new_root
282           Sets the document root to a new value only for the duration of the
283           current request.
284
285           Note the limited functionality under threaded MPMs.
286
287       ret: $docroot ( string )
288           The document root
289
290       since: 2.0.00
291
292   "get_handlers"
293       Returns a reference to a list of handlers enabled for a given phase.
294
295         $handlers_list = $r->get_handlers($hook_name);
296
297       obj: $r ( "Apache2::RequestRec object" )
298       arg1: $hook_name ( string )
299           a string representing the phase to handle (e.g. "PerlLogHandler")
300
301       ret: $handlers_list (ref to an ARRAY of CODE refs)
302           a list of handler subroutines CODE references
303
304       since: 2.0.00
305
306       See also: "$s->add_config"
307
308       For example:
309
310       A list of handlers configured to run at the response phase:
311
312         my @handlers = @{ $r->get_handlers('PerlResponseHandler') || [] };
313
314   "get_limit_req_body"
315       Return the limit on bytes in request msg body
316
317         $limit = $r->get_limit_req_body();
318
319       obj: $r ( "Apache2::RequestRec object" )
320           The current request
321
322       ret: $limit (integer)
323           the maximum number of bytes in the request msg body
324
325       since: 2.0.00
326
327   "get_server_name"
328       Get the current request's server name
329
330         $server = $r->get_server_name();
331
332       obj: $r ( "Apache2::RequestRec object" )
333           The current request
334
335       ret: $server ( string )
336           the server name
337
338       since: 2.0.00
339
340       For example, consruct a hostport string:
341
342         use Apache2::RequestUtil ();
343         my $hostport = join ':', $r->get_server_name, $r->get_server_port;
344
345   "get_server_port"
346       Get the current server port
347
348         $port = $r->get_server_port();
349
350       obj: $r ( "Apache2::RequestRec object" )
351           The current request
352
353       ret: $port ( integer )
354           The server's port number
355
356       since: 2.0.00
357
358       For example, consruct a hostport string:
359
360         use Apache2::RequestUtil ();
361         my $hostport = join ':', $r->get_server_name, $r->get_server_port;
362
363   "get_status_line"
364       Return the "Status-Line" for a given status code (excluding the HTTP-
365       Version field).
366
367         $status_line = Apache2::RequestUtil::get_status_line($status);
368
369       arg1: $status (integer)
370           The HTTP status code
371
372       ret: $status_line ( string )
373           The Status-Line
374
375           If an invalid or unknown status code is passed, "500 Internal
376           Server Error" will be returned.
377
378       since: 2.0.00
379
380       For example:
381
382         use Apache2::RequestUtil ();
383         print Apache2::RequestUtil::get_status_line(400);
384
385       will print:
386
387         400 Bad Request
388
389   "is_initial_req"
390       Determine whether the current request is the main request or a sub-
391       request
392
393         $is_initial = $r->is_initial_req();
394
395       obj: $r ( "Apache2::RequestRec object" )
396           A request or a sub-request object
397
398       ret: $is_initial ( boolean )
399           If true -- it's the main request, otherwise it's a sub-request
400
401       since: 2.0.00
402
403   "is_perl_option_enabled"
404       check whether a directory level "PerlOptions" flag is enabled or not.
405
406         $result = $r->is_perl_option_enabled($flag);
407
408       obj: $r ( "Apache2::RequestRec object" )
409       arg1: $flag ( string )
410       ret: $result ( boolean )
411       since: 2.0.00
412
413       For example to check whether the "SetupEnv" option is enabled for the
414       current request (which can be disabled with "PerlOptions -SetupEnv")
415       and populate the environment variables table if disabled:
416
417         $r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');
418
419       See also: PerlOptions and the equivalent function for server level
420       PerlOptions flags.
421
422   "location"
423       Get the path of the <Location> section from which the current
424       "Perl*Handler" is being called.
425
426         $location = $r->location();
427
428       obj: $r ( "Apache2::RequestRec object" )
429       ret: $location ( string )
430       since: 2.0.00
431
432   "location_merge"
433       Merge a given "<Location>" container into the current request object:
434
435         $ret = $r->location_merge($location);
436
437       obj: $r ( "Apache2::RequestRec object" )
438       arg1: $location ( string )
439           The argument in a "<Location>" section. For example to merge a
440           container:
441
442             <Location /foo>
443                 ...
444             </Location>
445
446           that argument will be /foo
447
448       ret: $ret ( boolean )
449           a true value if the merge was successful (i.e. the request
450           $location match was found), otherwise false.
451
452       since: 2.0.00
453
454       Useful for insertion of a configuration section into a custom
455       "Apache2::RequestRec" object, created via the
456       "Apache2::RequestRec->new()" method. See for example the Command Server
457       protocol example.
458
459   "new"
460       Create a new "Apache2::RequestRec" object.
461
462         $r = Apache2::RequestRec->new($c);
463         $r = Apache2::RequestRec->new($c, $pool);
464
465       obj: "Apache2::RequestRec" ( "Apache2::RequestRec class name" )
466       arg1: $c ("Apache2::Connection object")
467       opt arg2: $pool
468           If no $pool argument is passed, "$c->pool" is used. That means that
469           the created "Apache2::RequestRec" object will be valid as long as
470           the connection object is valid.
471
472       ret: $r ( "Apache2::RequestRec object" )
473       since: 2.0.00
474
475       It's possible to reuse the HTTP framework features outside the familiar
476       HTTP request cycle. It's possible to write your own full or partial
477       HTTP implementation without needing a running Apache server. You will
478       need the "Apache2::RequestRec" object in order to be able to reuse the
479       rich functionality supplied via this object.
480
481       See for example the Command Server protocol example which reuses HTTP
482       AAA model under non-HTTP protocol.
483
484   "no_cache"
485       Add/remove cache control headers:
486
487         $prev_no_cache = $r->no_cache($boolean);
488
489       obj: $r ( "Apache2::RequestRec object" )
490       arg1: $boolean ( boolean )
491           A true value sets the "no_cache" request record member to a true
492           value and inserts:
493
494             Pragma: no-cache
495             Cache-control: no-cache
496
497           into the response headers, indicating that the data being returned
498           is volatile and the client should not cache it.
499
500           A false value unsets the "no_cache" request record member and the
501           mentioned headers if they were previously set.
502
503       ret: $prev_no_cache ( boolean )
504           Should you care, the "no_cache" request record member value prior
505           to the change is returned.
506
507       since: 2.0.00
508
509       This method should be invoked before any response data has been sent
510       out.
511
512   "pnotes"
513       Share Perl variables between Perl HTTP handlers
514
515         $old_val  = $r->pnotes($key => $val);
516         $val      = $r->pnotes($key);
517         $hash_ref = $r->pnotes();
518
519       Note: sharing variables really means it. The variable is not copied.
520       Only its reference count is incremented. If it is changed after being
521       put in pnotes that change also affects the stored value. The following
522       example illustrates the effect:
523
524         my $v=1;                     my $v=1;
525         $r->pnotes( 'v'=>$v );       $r->pnotes->{v}=$v;
526         $v++;                        $v++;
527         my $x=$r->pnotes('v');       my $x=$r->pnotes->{v};
528
529       In both cases $x is 2 not 1. See also "Apache2::SafePnotes" on CPAN.
530
531       obj: $r ( "Apache2::RequestRec object" )
532       opt arg1: $key ( string )
533           A key value
534
535       opt arg2: $val ( SCALAR )
536           Any scalar value (e.g. a reference to an array)
537
538       ret: (3 different possible values)
539           if both, $key and $val are passed the previous value for $key is
540           returned if such existed, otherwise "undef" is returned.
541
542           if only $key is passed, the current value for the given key is
543           returned.
544
545           if no arguments are passed, a hash reference is returned, which can
546           then be directly accessed without going through the "pnotes()"
547           interface.
548
549       since: 2.0.00
550
551       This method provides functionality similar to
552       ("Apache2::RequestRec::notes"), but values can be any Perl variables.
553       That also means that it can be used only between Perl modules.
554
555       The values get reset automatically at the end of each HTTP request.
556
557       Examples:
558
559       Set a key/value pair:
560
561         $r->pnotes(foo => [1..5]);
562
563       Get the value:
564
565         $val = $r->pnotes("foo");
566
567       $val now contains an array ref containing 5 elements (1..5).
568
569       Now change the existing value:
570
571         $old_val = $r->pnotes(foo => ['a'..'c']);
572         $val = $r->pnotes("foo");
573
574       $old_val now contains an array ref with 5 elements (1..5) and $val
575       contains an array ref with 3 elements 'a', 'b', 'c'.
576
577       Alternatively you can access the hash reference with all pnotes values:
578
579         $pnotes = $r->pnotes;
580
581       Now we can read what's in there for the key foo:
582
583         $val = $pnotes->{foo};
584
585       and as before $val still gives us an array ref with 3 elements 'a',
586       'b', 'c'.
587
588       Now we can add elements to it:
589
590         push @{ $pnotes{foo} }, 'd'..'f';
591
592       and we can try to retrieve them using the hash and non-hash API:
593
594         $val1 = $pnotes{foo};
595         $val2 = $r->pnotes("foo");
596
597       Both $val1 and $val2 contain an array ref with 6 elements (letters 'a'
598       to 'f').
599
600       Finally to reset an entry you could just assign "undef" as a value:
601
602         $r->pnotes(foo => undef);
603
604       but the entry for the key foo still remains with the value "undef". If
605       you really want to completely remove it, use the hash interface:
606
607         delete $r->pnotes->{foo};
608
609   "psignature"
610       Get HTML describing the address and (optionally) admin of the server.
611
612         $sig = $r->psignature($prefix);
613
614       obj: $r ( "Apache2::RequestRec" )
615       arg1: $prefix ( string )
616           Text which is prepended to the return value
617
618       ret: $sig ( string )
619           HTML text describing the server. Note that depending on the value
620           of the "ServerSignature" directive, the function may return the
621           address, including the admin information or nothing at all.
622
623       since: 2.0.00
624
625   "request"
626       Get/set the ( "Apache2::RequestRec object" ) object for the current
627       request.
628
629         $r = Apache2::RequestUtil->request;
630              Apache2::RequestUtil->request($new_r);
631
632       obj: "Apache2" (class name)
633           The Apache class name
634
635       opt arg1: $new_r ( "Apache2::RequestRec object" )
636       ret: $r ( "Apache2::RequestRec object" )
637       since: 2.0.00
638
639       The get-able part of this method is only available if "PerlOptions
640       +GlobalRequest" is in effect or if "Apache2->request($new_r)" was
641       called earlier. So instead of setting "PerlOptions +GlobalRequest", one
642       can set the global request from within the handler.
643
644   "push_handlers"
645       Add one or more handlers to a list of handlers to be called for a given
646       phase.
647
648         $ok = $r->push_handlers($hook_name => \&handler);
649         $ok = $r->push_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
650
651       obj: $r ( "Apache2::RequestRec object" )
652       arg1: $hook_name ( string )
653           the phase to add the handlers to
654
655       arg2: $handlers ( CODE ref or SUB name or an ARRAY ref )
656           a single handler CODE reference or just a name of the subroutine
657           (fully qualified unless defined in the current package).
658
659           if more than one passed, use a reference to an array of CODE refs
660           and/or subroutine names.
661
662       ret: $ok ( boolean )
663           returns a true value on success, otherwise a false value
664
665       since: 2.0.00
666           See also: "$s->add_config"
667
668           Note that to push input/output filters you have to use
669           "Apache2::Filter" methods: "add_input_filter" and
670           "add_output_filter".
671
672       Examples:
673
674       A single handler:
675
676         $r->push_handlers(PerlResponseHandler => \&handler);
677
678       Multiple handlers:
679
680         $r->push_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
681
682       Anonymous functions:
683
684         $r->push_handlers(PerlLogHandler => sub { return Apache2::Const::OK });
685
686   "set_basic_credentials"
687       Populate the incoming request headers table ("headers_in") with
688       authentication headers for Basic Authorization as if the client has
689       submitted those in first place:
690
691         $r->set_basic_credentials($username, $password);
692
693       obj: $r ( "Apache2::RequestRec object" )
694       arg1: $username ( string )
695       arg2: $password ( string )
696       ret: no return value
697       since: 2.0.00
698
699       See for example the Command Server protocol example which reuses HTTP
700       AAA model under non-HTTP protocol.
701
702   "set_handlers"
703       Set a list of handlers to be called for a given phase. Any previously
704       set handlers are forgotten.
705
706         $ok = $r->set_handlers($hook_name => \&handler);
707         $ok = $r->set_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
708         $ok = $r->set_handlers($hook_name => []);
709         $ok = $r->set_handlers($hook_name => undef);
710
711       obj: $r ( "Apache2::RequestRec object" )
712       arg1: $hook_name ( string )
713           the phase to set the handlers in
714
715       arg2: $handlers (CODE ref or SUB name or an ARRAY ref)
716           a reference to a single handler CODE reference or just a name of
717           the subroutine (fully qualified unless defined in the current
718           package).
719
720           if more than one passed, use a reference to an array of CODE refs
721           and/or subroutine names.
722
723           if the argument is "undef" or "[]" the list of handlers is reset to
724           zero.
725
726       ret: $ok ( boolean )
727           returns a true value on success, otherwise a false value
728
729       since: 2.0.00
730
731       See also: "$s->add_config"
732
733       Examples:
734
735       A single handler:
736
737         $r->set_handlers(PerlResponseHandler => \&handler);
738
739       Multiple handlers:
740
741         $r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
742
743       Anonymous functions:
744
745         $r->set_handlers(PerlLogHandler => sub { return Apache2::Const::OK });
746
747       Reset any previously set handlers:
748
749         $r->set_handlers(PerlCleanupHandler => []);
750
751       or
752
753         $r->set_handlers(PerlCleanupHandler => undef);
754
755   "slurp_filename"
756       Slurp the contents of "$r->filename":
757
758         $content_ref = $r->slurp_filename($tainted);
759
760       obj: $r ( "Apache2::RequestRec object" )
761       arg1: $tainted (number)
762           If the server is run under the tainting mode ("-T") which we hope
763           you do, by default the returned data is tainted. If an optional
764           $tainted flag is set to zero, the data will be marked as non-
765           tainted.
766
767           Do not set this flag to zero unless you know what you are doing,
768           you may create a security hole in your program if you do. For more
769           information see the perlsec manpage.
770
771           If you wonder why this option is available, it is used internally
772           by the "ModPerl::Registry" handler and friends, because the CGI
773           scripts that it reads are considered safe (you could just as well
774           "require()" them).
775
776       ret: $content_ref ( SCALAR ref )
777           A reference to a string with the contents
778
779       excpt: "APR::Error"
780           Possible error codes could be: "APR::Const::EACCES" (permission
781           problems), "APR::Const::ENOENT" (file not found), and others. For
782           checking such error codes, see the documentation for, for example,
783           "APR::Status::is_EACCES" and "APR::Status::is_ENOENT".
784
785       since: 2.0.00
786
787       Note that if you assign to "$r->filename" you need to update its stat
788       record.
789

Copyright

794       mod_perl 2.0 and its core modules are copyrighted under The Apache
795       Software License, Version 2.0.
796

Authors

798       The mod_perl development team and numerous contributors.
799
800
801
802perl v5.10.1                      2007-11-12docs::api::Apache2::RequestUtil(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors