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

Copyright

818       mod_perl 2.0 and its core modules are copyrighted under The Apache
819       Software License, Version 2.0.
820

Authors

822       The mod_perl development team and numerous contributors.
823
824
825
826perl v5.8.8                       2006-11-19docs::api::Apache2::RequestUtil(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors