Apache2::RequestRec(3pm)

1docs::api::Apache2::ReqUuseesrtRCeocn(t3r)ibuted Perl Dodcoucmse:n:taaptii:o:nApache2::RequestRec(3)
2
3
4

NAME

6       Apache2::RequestRec - Perl API for Apache request record accessors
7

Synopsis

9         use Apache2::RequestRec ();
10
11         # set supported by the handler HTTP methods
12         $allowed = $r->allowed();
13
14         # auth type
15         $auth_type = $r->ap_auth_type();
16
17         # QUERY_STRING
18         $args = $r->args();
19
20         # non-parsed-headers handler
21         $status = $r->assbackwards();
22
23         # how many bytes were sent
24         $bytes_sent = $r->bytes_sent();
25
26         # client connection record
27         $c = $r->connection();
28
29         # "Content-Encoding" HTTP response header
30         $r->content_encoding("gzip");
31
32         # the languages of the content
33         $languages = $r->content_languages();
34
35         # "Content-Encoding" HTTP response header
36         $r->content_type('text/plain');
37
38         # special response headers table
39         $err_headers_out = $r->err_headers_out();
40
41         # request mapped filename
42         $filename = $r->filename();
43
44         # request finfo
45         $finfo = $r->finfo();
46
47         # 'SetHandler perl-script' equivalent
48         $r->handler('perl-script');
49
50         # was it a HEAD request?
51         $status = $r->header_only();
52
53         # request input headers table
54         $headers_in = $r->headers_in();
55
56         # request output headers table
57         $headers_out = $r->headers_out();
58
59         # hostname
60         $hostname = $r->hostname();
61
62         # input filters stack
63         $input_filters = $r->input_filters();
64
65         # get the main request obj in a sub-request
66         $main_r = $r->main();
67
68         # what's the current request (GET/POST/etc)?
69         $method = $r->method();
70
71         # what's the current method number?
72         $methnum = $r->method_number();
73
74         # current resource last modified time
75         $mtime = $r->mtime();
76
77         # next request object (in redirect)
78         $next_r = $r->next();
79
80         # there is no local copy
81         $r->no_local_copy();
82
83         # Apache ascii notes table
84         $notes = $r->notes();
85
86         # output filters stack
87         $output_filters = $r->output_filters();
88
89         # PATH_INFO
90         $path_info = $r->path_info();
91
92         # used in configuration directives modules
93         $per_dir_config = $r->per_dir_config();
94
95         # pool with life span of the current request
96         $p = $r->pool();
97
98         # previous request object in the internal redirect
99         $prev_r = $r->prev();
100
101         # connection level input filters stack
102         $proto_input_filters = $r->proto_input_filters();
103
104         # HTTP protocol version number
105         $proto_num = $r->proto_num();
106
107         # connection level output filters stack
108         $proto_output_filters = $r->proto_output_filters();
109
110         # the protocol, the client speaks: "HTTP/1.0", "HTTP/1.1", etc.
111         $protocol = $r->protocol();
112
113         # is it a proxy request
114         $status = $r->proxyreq($val);
115
116         # Time when the request started
117         $request_time = $r->request_time();
118
119         # server object
120         $s = $r->server();
121
122         # response status
123         $status = $r->status();
124
125         # response status line
126         $status_line = $r->status_line();
127
128         # manipulate %ENV of the subprocess
129         $r->subprocess_env;
130         $r->subprocess_env($key => $val);
131
132         # first HTTP request header
133         $request = $r->the_request();
134
135         # the URI without any parsing performed
136         $unparsed_uri = $r->unparsed_uri();
137
138         # The path portion of the URI
139         $uri = $r->uri();
140
141         # auth username
142         $user = $r->user();
143

Description

145       "Apache2::RequestRec" provides the Perl API for Apache request_rec
146       object.
147
148       The following packages extend the "Apache2::RequestRec" functionality:
149       "Apache2::Access", "Apache2::Log", "Apache2::RequestIO",
150       "Apache2::RequestUtil", "Apache2::Response", "Apache2::SubRequest" and
151       "Apache2::URI".
152

API

154       "Apache2::RequestRec" provides the following functions and/or methods:
155
156   "allowed"
157       Get/set the allowed methods bitmask.
158
159         $allowed      = $r->allowed();
160         $prev_allowed = $r->allowed($new_allowed);
161
162       obj: $r ( "Apache2::RequestRec object" )
163       opt arg1: $new_allowed ( bitmask )
164           Set the bitvector.
165
166       ret: $allowed ( bitmask )
167           returns $allowed, which is a bitvector of the allowed methods.
168
169           If the $new_allowed argument is passed, the value before the change
170           is returned.
171
172       since: 2.0.00
173
174       A handler must ensure that the request method is one that it is capable
175       of handling.  Generally modules should "Apache2::DECLINE" any request
176       methods they do not handle.  Prior to aborting the handler like this
177       the handler should set "$r->allowed" to the list of methods that it is
178       willing to handle.  This bitvector is used to construct the "Allow:"
179       header required for "OPTIONS" requests, and
180       "Apache2::Const::HTTP_METHOD_NOT_ALLOWED" (405) and
181       "Apache2::Const::HTTP_NOT_IMPLEMENTED" (501) status codes.
182
183       Since the default Apache handler deals with the "OPTIONS" method, all
184       response handlers can usually decline to deal with "OPTIONS". For
185       example if the response handler handles only "GET" and "POST" methods,
186       and not "OPTIONS", it may want to say:
187
188          use Apache2::Const -compile => qw(OK DECLINED M_GET M_POST M_OPTIONS);
189          if ($r->method_number == Apache2::Const::M_OPTIONS) {
190              $r->allowed($r->allowed | (1<<Apache2::Const::M_GET) | (1<<Apache2::Const::M_POST));
191              return Apache2::Const::DECLINED;
192          }
193
194       "TRACE" is always allowed, modules don't need to set it explicitly.
195
196       Since the default_handler will always handle a "GET", a module which
197       does *not* implement "GET" should probably return
198       "Apache2::Const::HTTP_METHOD_NOT_ALLOWED".  Unfortunately this means
199       that a script "GET" handler can't be installed by mod_actions.
200
201       For example, if the module can handle only POST method it could start
202       with:
203
204          use Apache2::Const -compile => qw(M_POST HTTP_METHOD_NOT_ALLOWED);
205          unless ($r->method_number == Apache2::Const::M_POST) {
206              $r->allowed($r->allowed | (1<<Apache2::Const::M_POST));
207              return Apache2::Const::HTTP_METHOD_NOT_ALLOWED;
208          }
209
210   "ap_auth_type"
211       If an authentication check was made, get or set the ap_auth_type slot
212       in the request record
213
214         $auth_type = $r->ap_auth_type();
215         $r->ap_auth_type($newval);
216
217       obj: $r ( "Apache2::RequestRec object" )
218       opt arg1: $newval (string)
219           If this argument is passed then a new auth type is assigned. For
220           example:
221
222             $r->auth_type('Basic');
223
224       ret: $auth_type (string)
225           If $newval is passed, nothing is returned. Otherwise the current
226           auth type is returned.
227
228       since: 2.0.00
229
230       ap_auth_type holds the authentication type that has been negotiated
231       between the client and server during the actual request.  Generally,
232       ap_auth_type is populated automatically when you call
233       "$r->get_basic_auth_pw" so you don't really need to worry too much
234       about it, but if you want to roll your own authentication mechanism
235       then you will have to populate ap_auth_type yourself.
236
237       Note that "$r->ap_auth_type" was "$r->connection->auth_type" in the
238       mod_perl 1.0 API.
239
240   "args"
241       Get/set the request QUERY string
242
243         $args      = $r->args();
244         $prev_args = $r->args($new_args);
245
246       obj: $r ( "Apache2::RequestRec object" )
247       opt arg1: $new_args ( string )
248           Optionally set the new QUERY string
249
250       ret: $args ( string )
251           The current QUERY string
252
253           If $new_args was passed, returns the value before the change.
254
255       since: 2.0.00
256
257   "assbackwards"
258       When set to a true value, Apache won't send any HTTP response headers
259       allowing you to send any headers.
260
261         $status      = $r->assbackwards();
262         $prev_status = $r->assbackwards($newval);
263
264       obj: $r ( "Apache2::RequestRec object" )
265       opt arg1: $newval (integer)
266           assign a new state.
267
268       ret: $status (integer)
269           current state.
270
271       since: 2.0.00
272
273       If you send your own set of headers, which includes the "Keep-Alive"
274       HTTP response header, you must make sure to increment the number of
275       requests served over this connection (which is normally done by the
276       core connection output filter "ap_http_header_filter", but skipped when
277       "assbackwards" is enabled).
278
279         $r->connection->keepalives($r->connection->keepalives + 1);
280
281       otherwise code relying on the value of "$r->connection->keepalives" may
282       malfunction. For example, this counter is used to tell when a new
283       request is coming in over the same connection to a filter that wants to
284       parse only HTTP headers (like "Apache2::Filter::HTTPHeadersFixup"). Of
285       course you will need to set "$r->connection->keepalive(1)" ) as well.
286
287   "bytes_sent"
288       The number of bytes sent to the client, handy for logging, etc.
289
290         $bytes_sent = $r->bytes_sent();
291
292       obj: $r ( "Apache2::RequestRec object" )
293       ret: $bytes_sent (integer)
294       since: 2.0.00
295
296       Though as of this writing in Apache 2.0 it doesn't really do what it
297       did in Apache 1.3. It's just set to the size of the response body.  The
298       issue is that buckets from one request may get buffered and not sent
299       during the lifetime of the request, so it's not easy to give a truly
300       accurate count of "bytes sent to the network for this response".
301
302   "connection"
303       Get the client connection record
304
305         $c = $r->connection();
306
307       obj: $r ( "Apache2::RequestRec object" )
308       ret: $c ( "Apache2::Connection object" )
309       since: 2.0.00
310
311   "content_encoding"
312       Get/set content encoding (the "Content-Encoding" HTTP header).  Content
313       encodings are string like "gzip" or "compress".
314
315         $ce      = $r->content_encoding();
316         $prev_ce = $r->content_encoding($new_ce);
317
318       obj: $r ( "Apache2::RequestRec object" )
319       opt arg1: $new_ce ( string )
320           If passed, sets the content encoding to a new value. It must be a
321           lowercased string.
322
323       ret: $ce ( string )
324           The current content encoding.
325
326           If $new_ce is passed, then the previous value is returned.
327
328       since: 2.0.00
329
330       For example, here is how to send a gzip'ed response:
331
332         require Compress::Zlib;
333         $r->content_type("text/plain");
334         $r->content_encoding("gzip");
335         $r->print(Compress::Zlib::memGzip("some text to be gzipped));
336
337   "content_languages"
338       Get/set content languages (the "Content-Language" HTTP header).
339       Content languages are string like "en" or "fr".
340
341         $languages = $r->content_languages();
342         $prev_lang = $r->content_languages($nev_lang);
343
344       obj: $r ( "Apache2::RequestRec object" )
345       opt arg1: $new_lang ( ARRAY ref )
346           If passed, sets the content languages to new values. It must be an
347           ARRAY reference of language names, like "en" or "fr"
348
349       ret: $languages ( ARRAY ref )
350           The current list of content languages, as an ARRAY reference.
351
352           If $new_lang is passed, then the previous value is returned.
353
354       since: 2.0.00
355
356   "content_type"
357       Get/set the HTTP response Content-type header value.
358
359         my $content_type      = $r->content_type();
360         my $prev_content_type = $r->content_type($new_content_type);
361
362       obj: $r ( "Apache2::RequestRec object" )
363       opt arg1: $new_content_type (MIME type string)
364           Assign a new HTTP response content-type. It will affect the
365           response only if HTTP headers weren't sent yet.
366
367       ret: $content_type
368           The current content-type value.
369
370           If $new_content_type was passed, the previous value is returned
371           instead.
372
373       since: 2.0.00
374
375       For example, set the "Content-type" header to text/plain.
376
377         $r->content_type('text/plain');
378
379       If you set this header via the "headers_out" table directly, it will be
380       ignored by Apache. So do not do that.
381
382   "err_headers_out"
383       Get/set MIME response headers, printed even on errors and persist
384       across internal redirects.
385
386         $err_headers_out = $r->err_headers_out();
387
388       obj: $r ( "Apache2::RequestRec object" )
389       ret: $err_headers_out ( "APR::Table object" )
390       since: 2.0.00
391
392       The difference between "headers_out" and "err_headers_out", is that the
393       latter are printed even on error, and persist across internal redirects
394       (so the headers printed for "ErrorDocument" handlers will have them).
395
396       For example, if a handler wants to return a 404 response, but
397       nevertheless to set a cookie, it has to be:
398
399         $r->err_headers_out->add('Set-Cookie' => $cookie);
400         return Apache2::Const::NOT_FOUND;
401
402       If the handler does:
403
404         $r->headers_out->add('Set-Cookie' => $cookie);
405         return Apache2::Const::NOT_FOUND;
406
407       the "Set-Cookie" header won't be sent.
408
409   "filename"
410       Get/set the filename on disk corresponding to this response (the result
411       of the URI --> filename translation).
412
413         $filename      = $r->filename();
414         $prev_filename = $r->filename($new_filename);
415
416       obj: $r ( "Apache2::RequestRec object" )
417       opt arg1: $new_filename ( string )
418           new value
419
420       ret: $filename ( string )
421           the current filename, or the previous value if the optional
422           $new_filename argument was passed
423
424       since: 2.0.00
425
426       Note that if you change the filename after the
427       "PerlMapToStorageHandler" phase was run and expect Apache to serve it,
428       you need to update its "stat" record, like so:
429
430         use Apache2::RequestRec ();
431         use APR::Finfo ();
432         use APR::Const -compile => qw(FINFO_NORM);
433         $r->filename($newfile);
434         $r->finfo(APR::Finfo::stat($newfile, APR::Const::FINFO_NORM, $r->pool));
435
436       if you don't, Apache will still try to use the previously cached
437       information about the previously set value of the filename.
438
439   "finfo"
440       Get and set the finfo request record member:
441
442         $finfo = $r->finfo();
443         $r->finfo($finfo);
444
445       obj: $r ( "Apache2::RequestRec object" )
446       opt arg1: $finfo ( "APR::Finfo object" )
447       ret: $finfo ( "APR::Finfo object" )
448           Always returns the current object.
449
450           Due to the internal Apache implementation it's not possible to have
451           two different objects originating from "$r->finfo" at the same
452           time. Whenever "$r->finfo" is updated all objects will be updated
453           too to the latest value.
454
455       since: 2.0.00
456
457       Most of the time, this method is used to get the "finfo" member. The
458       only reason you may want to set it is you need to use it before the
459       Apache's default map_to_storage phase is called.
460
461       Examples:
462
463       •   What Apache thinks is the current request filename (post the
464           "PerlMapToStorageHandler" phase):
465
466             use Apache2::RequestRec ();
467             use APR::Finfo ();
468             print $r->finfo->fname;
469
470       •   Populate the "finfo" member (normally, before the
471           "PerlMapToStorageHandler" phase):
472
473             use APR::Finfo ();
474             use APR::Const -compile => qw(FINFO_NORM);
475
476             my $finfo = APR::Finfo::stat(__FILE__, APR::Const::FINFO_NORM, $r->pool);
477             $r->finfo($finfo);
478
479   "handler"
480       Get/set the equivalent of the "SetHandler" directive.
481
482         $handler      = $r->handler();
483         $prev_handler = $r->handler($new_handler);
484
485       obj: $r ( "Apache2::RequestRec object" )
486       opt arg1: $new_handler ( string )
487           the new handler.
488
489       ret: $handler ( string )
490           the current handler.
491
492           If $new_handler is passed, the previous value is returned.
493
494       since: 2.0.00
495
496   "header_only"
497       Did the client has asked for headers only? e.g. if the request method
498       was HEAD.
499
500         $status = $r->header_only();
501
502       obj: $r ( "Apache2::RequestRec object" )
503       ret: $status ( boolean )
504           Returns true if the client is asking for headers only, false
505           otherwise
506
507       since: 2.0.00
508
509   "headers_in"
510       Get/set the request MIME headers:
511
512         $headers_in = $r->headers_in();
513
514       obj: $r ( "Apache2::RequestRec object" )
515       ret: $headers_in ( "APR::Table object" )
516       since: 2.0.00
517
518       This table is available starting from the "PerlHeaderParserHandler"
519       phase.
520
521       For example you can use it to retrieve the cookie value sent by the
522       client, in the "Cookie:" header:
523
524           my $cookie = $r->headers_in->{Cookie} || '';
525
526   "headers_out"
527       Get/set MIME response headers, printed only on 2xx responses.
528
529         $headers_out = $r->headers_out();
530
531       obj: $r ( "Apache2::RequestRec object" )
532       ret: $headers_out ( "APR::Table object" )
533       since: 2.0.00
534
535       See also "err_headers_out", which allows to set headers for non-2xx
536       responses and persist across internal redirects.
537
538   "hostname"
539       Host, as set by full URI or Host:
540
541         $hostname = $r->hostname();
542         $prev_hostname = $r->hostname($new_hostname);
543
544       obj: $r ( "Apache2::RequestRec object" )
545       opt arg1: $new_hostname ( string )
546           new value
547
548       ret: $hostname ( string )
549           the current hostname, or the previous value if the optional
550           $new_hostname argument was passed
551
552       since: 2.0.00
553
554   "input_filters"
555       Get/set the first filter in a linked list of request level input
556       filters:
557
558         $input_filters      = $r->input_filters();
559         $prev_input_filters = $r->input_filters($new_input_filters);
560
561       obj: $r ( "Apache2::RequestRec object" )
562       opt arg1: $new_input_filters
563           Set a new value
564
565       ret: $input_filters ( "Apache2::Filter object" )
566           The first filter in the request level input filters chain.
567
568           If $new_input_filters was passed, returns the previous value.
569
570       since: 2.0.00
571
572       For example instead of using "$r->read()" to read the POST data, one
573       could use an explicit walk through incoming bucket brigades to get that
574       data. The following function read_post() does just that (in fact that's
575       what "$r->read()" does behind the scenes):
576
577         use APR::Brigade ();
578         use APR::Bucket ();
579         use Apache2::Filter ();
580
581         use Apache2::Const -compile => qw(MODE_READBYTES);
582         use APR::Const    -compile => qw(SUCCESS BLOCK_READ);
583
584         use constant IOBUFSIZE => 8192;
585
586         sub read_post {
587             my $r = shift;
588
589             my $bb = APR::Brigade->new($r->pool,
590                                        $r->connection->bucket_alloc);
591
592             my $data = '';
593             my $seen_eos = 0;
594             do {
595                 $r->input_filters->get_brigade($bb, Apache2::Const::MODE_READBYTES,
596                                                APR::Const::BLOCK_READ, IOBUFSIZE);
597
598                 for (my $b = $bb->first; $b; $b = $bb->next($b)) {
599                     if ($b->is_eos) {
600                         $seen_eos++;
601                         last;
602                     }
603
604                     if ($b->read(my $buf)) {
605                         $data .= $buf;
606                     }
607
608                     $b->remove; # optimization to reuse memory
609                 }
610
611             } while (!$seen_eos);
612
613             $bb->destroy;
614
615             return $data;
616         }
617
618       As you can see "$r->input_filters" gives us a pointer to the last of
619       the top of the incoming filters stack.
620
621   "main"
622       Get the main request record
623
624         $main_r = $r->main();
625
626       obj: $r ( "Apache2::RequestRec object" )
627       ret: $main_r ( "Apache2::RequestRec object" )
628           If the current request is a sub-request, this method returns a
629           blessed reference to the main request structure. If the current
630           request is the main request, then this method returns "undef".
631
632           To figure out whether you are inside a main request or a
633           sub-request/internal redirect, use "$r->is_initial_req".
634
635       since: 2.0.00
636
637   "method"
638       Get/set the current request method (e.g. "GET", "HEAD", "POST", etc.):
639
640         $method     = $r->method();
641         $pre_method = $r->method($new_method);
642
643       obj: $r ( "Apache2::RequestRec object" )
644       opt arg1: $new_method ( string )
645           a new value
646
647       ret: $method ( string )
648           The current method as a string
649
650           if $new_method was passed the previous value is returned.
651
652       since: 2.0.00
653
654   "method_number"
655       Get/set the HTTP method, issued by the client ("Apache2::Const::M_GET",
656       "Apache2::Const::M_POST", etc.)
657
658         $methnum      = $r->method_number();
659         $prev_methnum = $r->method_number($new_methnum);
660
661       obj: $r ( "Apache2::RequestRec object" )
662       opt arg1: $new_methnum ( "Apache2::Const :methods constant" )
663           a new value
664
665       ret: $methnum ( "Apache2::Const :methods constant" )
666           The current method as a number
667
668           if $new_methnum was passed the previous value is returned.
669
670       since: 2.0.00
671
672       See the "$r->allowed" entry for examples.
673
674   "mtime"
675       Last modified time of the requested resource
676
677         $mtime      = $r->mtime();
678         $prev_mtime = $r->mtime($new_mtime);
679
680       obj: $r ( "Apache2::RequestRec object" )
681       opt arg1: $new_mtime (epoch seconds).
682           a new value
683
684       ret: $mtime (epoch seconds).
685           the current value
686
687           if $new_mtime was passed the previous value is returned.
688
689       since: 2.0.00
690
691   "next"
692       Pointer to the redirected request if this is an external redirect
693
694         $next_r = $r->next();
695
696       obj: $r ( "Apache2::RequestRec object" )
697       ret: $next_r ( "Apache2::RequestRec object" )
698           returns a blessed reference to the next (internal) request
699           structure or "undef" if there is no next request.
700
701       since: 2.0.00
702
703   "no_local_copy"
704       There is no local copy of this response
705
706         $status = $r->no_local_copy();
707
708       obj: $r ( "Apache2::RequestRec object" )
709       ret: $status (integer)
710       since: 2.0.00
711
712       Used internally in certain sub-requests to prevent sending
713       "Apache2::Const::HTTP_NOT_MODIFIED" for a fragment or error documents.
714       For example see the implementation in modules/filters/mod_include.c.
715
716       Also used internally in "$r->meets_conditions" -- if set to a true
717       value, the conditions are always met.
718
719   "notes"
720       Get/set text notes for the duration of this request. These notes can be
721       passed from one module to another (not only mod_perl, but modules in
722       any other language):
723
724         $notes      = $r->notes();
725         $prev_notes = $r->notes($new_notes);
726
727       obj: $r ( "Apache2::RequestRec object" )
728       opt arg1: $new_notes ( "APR::Table object" )
729       ret: $notes ( "APR::Table object" )
730           the current notes table.
731
732           if the $new_notes argument was passed, returns the previous value.
733
734       since: 2.0.00
735
736       If you want to pass Perl structures, you can use "$r->pnotes".
737
738       Also see "$c->notes"
739
740   "output_filters"
741       Get the first filter in a linked list of request level output filters:
742
743         $output_filters      = $r->output_filters();
744         $prev_output_filters = $r->output_filters($new_output_filters);
745
746       obj: $r ( "Apache2::RequestRec object" )
747       opt arg1: $new_output_filters
748           Set a new value
749
750       ret: $output_filters ( "Apache2::Filter object" )
751           The first filter in the request level output filters chain.
752
753           If $new_output_filters was passed, returns the previous value.
754
755       since: 2.0.00
756
757       For example instead of using "$r->print()" to send the response body,
758       one could send the data directly to the first output filter. The
759       following function send_response_body() does just that:
760
761         use APR::Brigade ();
762         use APR::Bucket ();
763         use Apache2::Filter ();
764
765         sub send_response_body {
766             my ($r, $data) = @_;
767
768             my $bb = APR::Brigade->new($r->pool,
769                                        $r->connection->bucket_alloc);
770
771             my $b = APR::Bucket->new($bb->bucket_alloc, $data);
772             $bb->insert_tail($b);
773             $r->output_filters->fflush($bb);
774             $bb->destroy;
775         }
776
777       In fact that's what "$r->read()" does behind the scenes. But it also
778       knows to parse HTTP headers passed together with the data and it also
779       implements buffering, which the above function does not.
780
781   "path_info"
782       Get/set the "PATH_INFO", what is left in the path after the URI -->
783       filename translation:
784
785         $path_info      = $r->path_info();
786         $prev_path_info = $r->path_info($path_info);
787
788       obj: $r ( "Apache2::RequestRec object" )
789       opt arg1: $path_info ( string )
790           Set a new value
791
792       ret: $path_info ( string )
793           Return the current value.
794
795           If the optional argument $path_info is passed, the previous value
796           is returned.
797
798       since: 2.0.00
799
800   "per_dir_config"
801       Get the dir config vector:
802
803         $per_dir_config = $r->per_dir_config();
804
805       obj: $r ( "Apache2::RequestRec object" )
806       ret: $per_dir_config ( "Apache2::ConfVector object" )
807       since: 2.0.00
808
809       For an indepth discussion, refer to the Apache Server Configuration
810       Customization in Perl chapter.
811
812   "pool"
813       The pool associated with the request
814
815         $p = $r->pool();
816
817       obj: $r ( "Apache2::RequestRec object" )
818       ret: $p ( "APR::Pool object" )
819       since: 2.0.00
820
821   "prev"
822       Pointer to the previous request if this is an internal redirect
823
824         $prev_r = $r->prev();
825
826       obj: $r ( "Apache2::RequestRec object" )
827       ret: $prev_r ( "Apache2::RequestRec object" )
828           a blessed reference to the previous (internal) request structure or
829           "undef" if there is no previous request.
830
831       since: 2.0.00
832
833   "proto_input_filters"
834       Get the first filter in a linked list of protocol level input filters:
835
836         $proto_input_filters      = $r->proto_input_filters();
837         $prev_proto_input_filters = $r->proto_input_filters($new_proto_input_filters);
838
839       obj: $r ( "Apache2::RequestRec object" )
840       opt arg1: $new_proto_input_filters
841           Set a new value
842
843       ret: $proto_input_filters ( "Apache2::Filter object" )
844           The first filter in the protocol level input filters chain.
845
846           If $new_proto_input_filters was passed, returns the previous value.
847
848       since: 2.0.00
849
850       "$r->proto_input_filters" points to the same filter as
851       "$r->connection->input_filters".
852
853   "proto_num"
854       Get current request's HTTP protocol version number
855
856         $proto_num = $r->proto_num();
857
858       obj: $r ( "Apache2::RequestRec object" )
859       ret: $proto_num (integer)
860           current request's HTTP protocol version number, e.g.: HTTP/1.0 ==
861           1000, HTTP/1.1 = 1001
862
863       since: 2.0.00
864
865   "proto_output_filters"
866       Get the first filter in a linked list of protocol level output filters:
867
868         $proto_output_filters      = $r->proto_output_filters();
869         $prev_proto_output_filters = $r->proto_output_filters($new_proto_output_filters);
870
871       obj: $r ( "Apache2::RequestRec object" )
872       opt arg1: $new_proto_output_filters
873           Set a new value
874
875       ret: $proto_output_filters ( "Apache2::Filter object" )
876           The first filter in the protocol level output filters chain.
877
878           If $new_proto_output_filters was passed, returns the previous
879           value.
880
881       since: 2.0.00
882
883       "$r->proto_output_filters" points to the same filter as
884       "$r->connection->output_filters".
885
886   "protocol"
887       Get a string identifying the protocol that the client speaks.
888
889         $protocol = $r->protocol();
890
891       obj: $r ( "Apache2::RequestRec object" )
892       ret: $protocl ( string )
893           Typical values are "HTTP/1.0" or "HTTP/1.1".
894
895           If the client didn't specify the protocol version, the default is
896           "HTTP/0.9"
897
898       since: 2.0.00
899
900   "proxyreq"
901       Get/set the proxyrec request record member and optionally adjust other
902       related fields.
903
904         $status = $r->proxyreq($val);
905
906       obj: $r ( "Apache2::RequestRec object" )
907       opt arg1: $val ( integer )
908           PROXYREQ_NONE, PROXYREQ_PROXY, PROXYREQ_REVERSE, PROXYREQ_RESPONSE
909
910       ret: $status ( integer )
911           If $val is defined the proxyrec member will be set to that value
912           and previous value will be returned.
913
914           If $val is not passed, and "$r->proxyreq" is not true, and the
915           proxy request is matching the current vhost (scheme, hostname and
916           port), the proxyrec member will be set to PROXYREQ_PROXY and that
917           value will be returned. In addition "$r->uri" is set to
918           "$r->unparsed_uri" and "$r->filename" is set to
919           ""modperl-proxy:".$r->uri". If those conditions aren't true 0 is
920           returned.
921
922       since: 2.0.00
923
924       For example to turn a normal request into a proxy request to be handled
925       on the same server in the "PerlTransHandler" phase run:
926
927         my $real_url = $r->unparsed_uri;
928         $r->proxyreq(Apache2::Const::PROXYREQ_PROXY);
929         $r->uri($real_url);
930         $r->filename("proxy:$real_url");
931         $r->handler('proxy-server');
932
933       Also remember that if you want to turn a proxy request into a non-proxy
934       request, it's not enough to call:
935
936         $r->proxyreq(Apache2::Const::PROXYREQ_NONE);
937
938       You need to adjust "$r->uri" and "$r->filename" as well if you run that
939       code in "PerlPostReadRequestHandler" phase, since if you don't --
940       "mod_proxy"'s own post_read_request handler will override your settings
941       (as it will run after the mod_perl handler).
942
943       And you may also want to add
944
945         $r->set_handlers(PerlResponseHandler => []);
946
947       so that any response handlers which match apache directives will not
948       run in addition to the mod_proxy content handler.
949
950   "request_time"
951       Time when the request started
952
953         $request_time = $r->request_time();
954
955       obj: $r ( "Apache2::RequestRec object" )
956       ret: $request_time (epoch seconds).
957       since: 2.0.00
958
959   "server"
960       Get the "Apache2::Server" object for the server the request $r is
961       running under.
962
963         $s = $r->server();
964
965       obj: $r ( "Apache2::RequestRec object" )
966       ret: $s ( "Apache2::ServerRec object" )
967       since: 2.0.00
968
969   "status"
970       Get/set the reply status for the client request.
971
972         $status      = $r->status();
973         $prev_status = $r->status($new_status);
974
975       obj: $r ( "Apache2::RequestRec object" )
976       opt arg1: $new_status ( integer )
977           If $new_status is passed the new status is assigned.
978
979           Normally you would use some "Apache2::Const constant", e.g.
980           "Apache2::Const::REDIRECT".
981
982       ret: $newval ( integer )
983           The current value.
984
985           If $new_status is passed the old value is returned.
986
987       since: 2.0.00
988
989       Usually you will set this value indirectly by returning the status code
990       as the handler's function result.  However, there are rare instances
991       when you want to trick Apache into thinking that the module returned an
992       "Apache2::Const::OK" status code, but actually send the browser a non-
993       OK status. This may come handy when implementing an HTTP proxy handler.
994       The proxy handler needs to send to the client, whatever status code the
995       proxied server has returned, while returning "Apache2::Const::OK" to
996       Apache. e.g.:
997
998         $r->status($some_code);
999         return Apache2::Const::OK
1000
1001       See also "$r->status_line", which. if set, overrides "$r->status".
1002
1003   "status_line"
1004       Get/set the response status line.  The status line is a string like
1005       "200 Document follows" and it will take precedence over the value
1006       specified using the "$r->status()" described above.
1007
1008         $status_line      = $r->status_line();
1009         $prev_status_line = $r->status_line($new_status_line);
1010
1011       obj: $r ( "Apache2::RequestRec object" )
1012       opt arg1: $new_status_line ( string )
1013       ret: $status_line ( string )
1014       since: 2.0.00
1015
1016       When discussing "$r->status" we have mentioned that sometimes a handler
1017       runs to a successful completion, but may need to return a different
1018       code, which is the case with the proxy server. Assuming that the proxy
1019       handler forwards to the client whatever response the proxied server has
1020       sent, it'll usually use status_line(), like so:
1021
1022         $r->status_line($response->code() . ' ' . $response->message());
1023         return Apache2::Const::OK;
1024
1025       In this example $response could be for example an "HTTP::Response"
1026       object, if "LWP::UserAgent" was used to implement the proxy.
1027
1028       This method is also handy when you extend the HTTP protocol and add new
1029       response codes. For example you could invent a new error code and tell
1030       Apache to use that in the response like so:
1031
1032         $r->status_line("499 We have been FooBared");
1033         return Apache2::Const::OK;
1034
1035       Here 499 is the new response code, and We have been FooBared is the
1036       custom response message.
1037
1038   "subprocess_env"
1039       Get/set the Apache "subprocess_env" table, or optionally set the value
1040       of a named entry.
1041
1042                      $r->subprocess_env;
1043         $env_table = $r->subprocess_env;
1044
1045                $r->subprocess_env($key => $val);
1046         $val = $r->subprocess_env($key);
1047
1048       obj: $r ( "Apache2::RequestRec object" )
1049       opt arg1: $key ( string )
1050       opt arg2: $val ( string )
1051       ret: "..."
1052       since: 2.0.00
1053
1054       When called in VOID context with no arguments, it populate %ENV with
1055       special variables (e.g. $ENV{QUERY_STRING}) like mod_cgi does.
1056
1057       When called in a non-VOID context with no arguments, it returns an
1058       "APR::Table object".
1059
1060       When the $key argument (string) is passed, it returns the corresponding
1061       value (if such exists, or "undef". The following two lines are
1062       equivalent:
1063
1064         $val = $r->subprocess_env($key);
1065         $val = $r->subprocess_env->get($key);
1066
1067       When the $key and the $val arguments (strings) are passed, the value is
1068       set. The following two lines are equivalent:
1069
1070         $r->subprocess_env($key => $val);
1071         $r->subprocess_env->set($key => $val);
1072
1073       The "subprocess_env" "table" is used by "Apache2::SubProcess", to pass
1074       environment variables to externally spawned processes. It's also used
1075       by various Apache modules, and you should use this table to pass the
1076       environment variables. For example if in "PerlHeaderParserHandler" you
1077       do:
1078
1079          $r->subprocess_env(MyLanguage => "de");
1080
1081       you can then deploy "mod_include" and write in .shtml document:
1082
1083          <!--#if expr="$MyLanguage = en" -->
1084          English
1085          <!--#elif expr="$MyLanguage = de" -->
1086          Deutsch
1087          <!--#else -->
1088          Sorry
1089          <!--#endif -->
1090
1091   "the_request"
1092       First HTTP request header
1093
1094         $request = $r->the_request();
1095         $old_request = $r->uri($new_request);
1096
1097       obj: $r ( "Apache2::RequestRec object" )
1098       opt arg1: $new_request ( string )
1099       ret: $request ( string )
1100           For example:
1101
1102             GET /foo/bar/my_path_info?args=3 HTTP/1.0
1103
1104       since: 2.0.00
1105
1106   "unparsed_uri"
1107       The URI without any parsing performed
1108
1109         $unparsed_uri = $r->unparsed_uri();
1110
1111       obj: $r ( "Apache2::RequestRec object" )
1112       ret: $unparsed_uri ( string )
1113       since: 2.0.00
1114
1115       If for example the request was:
1116
1117         GET /foo/bar/my_path_info?args=3 HTTP/1.0
1118
1119       "$r->uri" returns:
1120
1121         /foo/bar/my_path_info
1122
1123       whereas "$r->unparsed_uri" returns:
1124
1125         /foo/bar/my_path_info?args=3
1126
1127   "uri"
1128       The path portion of the URI
1129
1130         $uri         = $r->uri();
1131         my $prec_uri = $r->uri($new_uri);
1132
1133       obj: $r ( "Apache2::RequestRec object" )
1134       opt arg1: $new_uri ( string )
1135       ret: $uri ( string )
1136       since: 2.0.00
1137
1138       See the example in the "$r->unparsed_uri" section.
1139
1140   "user"
1141       Get the user name, if an authentication process was successful. Or set
1142       it.
1143
1144         $user      = $r->user();
1145         $prev_user = $r->user($new_user);
1146
1147       obj: $r ( "Apache2::RequestRec object" )
1148       opt arg1: $new_user ( string )
1149           Pass $new_user to set a new value
1150
1151       ret: $user ( string )
1152           The current username if an authentication process was successful.
1153
1154           If $new_user was passed, the previous value is returned.
1155
1156       since: 2.0.00
1157
1158       For example, let's print the username passed by the client:
1159
1160         my ($res, $sent_pw) = $r->get_basic_auth_pw;
1161         return $res if $res != Apache2::Const::OK;
1162         print "User: ", $r->user;
1163

Unsupported API

1165       "Apache2::RequestRec" also provides auto-generated Perl interface for a
1166       few other methods which aren't tested at the moment and therefore their
1167       API is a subject to change. These methods will be finalized later as a
1168       need arises. If you want to rely on any of the following methods please
1169       contact the the mod_perl development mailing list so we can help each
1170       other take the steps necessary to shift the method to an officially
1171       supported API.
1172
1173   "allowed_methods"
1174       META: Autogenerated - needs to be reviewed/completed
1175
1176       List of allowed methods
1177
1178         $list = $r->allowed_methods();
1179
1180       obj: $r ( "Apache2::RequestRec object" )
1181       ret: $list ( "Apache2::MethodList object" )
1182       since: 2.0.00
1183
1184       META: Apache2::MethodList is not available at the moment
1185
1186   "allowed_xmethods"
1187       META: Autogenerated - needs to be reviewed/completed
1188
1189       Array of extension methods
1190
1191         $array = $r->allowed_xmethods();
1192
1193       obj: $r ( "Apache2::RequestRec object" )
1194       ret: $array ( "APR::ArrayHeader object" )
1195       since: 2.0.00
1196
1197       META: APR::ArrayHeader is not available at the moment
1198
1199   "request_config"
1200       Config vector containing pointers to request's per-server config
1201       structures
1202
1203         $ret = $r->request_config($newval);
1204
1205       obj: $r ( "Apache2::RequestRec object" )
1206       opt arg1: $newval ( "Apache2::ConfVector object" )
1207       since: 2.0.00
1208
1209   "used_path_info"
1210       META: Autogenerated - needs to be reviewed/completed
1211
1212       Flag for the handler to accept or reject path_info on the current
1213       request.  All modules should respect the AP_REQ_ACCEPT_PATH_INFO and
1214       AP_REQ_REJECT_PATH_INFO values, while AP_REQ_DEFAULT_PATH_INFO
1215       indicates they may follow existing conventions.  This is set to the
1216       user's preference upon HOOK_VERY_FIRST of the fixups.
1217
1218         $ret = $r->used_path_info($newval);
1219
1220       obj: $r ( "Apache2::RequestRec object" )
1221       arg1: $newval (integer)
1222       since: 2.0.00
1223

Copyright

1228       mod_perl 2.0 and its core modules are copyrighted under The Apache
1229       Software License, Version 2.0.
1230

Authors

1232       The mod_perl development team and numerous contributors.
1233
1234
1235
1236perl v5.38.0                      2023-07-20 docs::api::Apache2::RequestRec(3)