Apache2::CmdParms(3pm)

1docs::api::Apache2::CmdUPsaerrmsC(o3n)tributed Perl Docudmoecnst:a:taipoin::Apache2::CmdParms(3)
2
3
4

NAME

6       Apache2::CmdParms - Perl API for Apache command parameters object
7

Synopsis

9         use Apache2::CmdParms ();
10         use Apache2::Module ();
11         use Apache2::Const -compile => qw(NOT_IN_LOCATION);
12
13         my @directives = (
14           {
15             name => 'MyDirective',
16             cmd_data => 'some extra data',
17           },
18         );
19
20         Apache2::Module::add(__PACKAGE__, \@directives);
21
22         sub MyDirective {
23             my ($self, $parms, $args) = @_;
24
25             # push config
26             $parms->add_config(['ServerTokens off']);
27
28             # this command's command object
29             $cmd = $parms->cmd;
30
31             # check the current command's context
32             $error = $parms->check_cmd_context(Apache2::Const::NOT_IN_LOCATION);
33
34             # this command's context
35             $context = $parms->context;
36
37             # this command's directive object
38             $directive = $parms->directive;
39
40             # the extra information passed thru cmd_data to
41             # Apache2::Module::add()
42             $info = $parms->info;
43
44             # which methods are <Limit>ed ?
45             $is_limited = $parms->method_is_limited('GET');
46
47             # which allow-override bits are set
48             $override = $parms->override;
49
50             # which Options are allowed by AllowOverride (since Apache 2.2)
51             $override = $parms->override_opts;
52
53             # the path this command is being invoked in
54             $path = $parms->path;
55
56             # this command's pool
57             $p = $parms->pool;
58
59             # this command's configuration time pool
60             $p = $parms->temp_pool;
61         }
62

Description

64       "Apache2::CmdParms" provides the Perl API for Apache command parameters
65       object.
66

API

68       "Apache2::CmdParms" provides the following functions and/or methods:
69
70   "add_config"
71       Dynamically add Apache configuration at request processing runtime:
72
73         $parms->add_config($lines);
74
75       obj: $parms ( "Apache2::CmdParms object" )
76       arg1: $lines (ARRAY ref)
77           An ARRAY reference containing configuration lines per element,
78           without the new line terminators.
79
80       ret: no return value
81       since: 2.0.00
82
83       See also: "$s->add_config", "$r->add_config"
84
85   "check_cmd_context"
86       Check the current command against a context bitmask of forbidden
87       contexts.
88
89         $error = $parms->check_cmd_context($check);
90
91       obj: $parms ( "Apache2::CmdParms object" )
92       arg1: $check ( "Apache2::Const :context constant" )
93           the context to check against.
94
95       ret: $error ( string / undef )
96           If the context is forbidden, this method returns a textual
97           description of why it was forbidden. If the context is permitted,
98           this method returns "undef".
99
100       since: 2.0.00
101
102       For example here is how to check whether a command is allowed in the
103       "<Location>" container:
104
105         use Apache2::Const -compile qw(NOT_IN_LOCATION);
106         if (my $error = $parms->check_cmd_context(Apache2::Const::NOT_IN_LOCATION)) {
107             die "directive ... not allowed in <Location> context"
108         }
109
110   "cmd"
111       This module's command information
112
113         $cmd = $parms->cmd();
114
115       obj: $parms ( "Apache2::CmdParms object" )
116       ret: $cmd ( "Apache2::Command object" )
117       since: 2.0.00
118
119   "directive"
120       This command's directive object in the configuration tree
121
122         $directive = $parms->directive;
123
124       obj: $parms ( "Apache2::CmdParms object" )
125       ret: $directive ( "Apache2::Directive object" )
126           The current directive node in the configuration tree
127
128       since: 2.0.00
129
130   "info"
131       The extra information passed through "cmd_data" in
132       Apache2::Module::add().
133
134         $info = $parms->info;
135
136       obj: $parms ( "Apache2::CmdParms object" )
137       ret: $info ( string )
138           The string passed in "cmd_data"
139
140       since: 2.0.00
141
142       For example here is how to pass arbitrary information to a directive
143       subroutine:
144
145         my @directives = (
146           {
147             name => 'MyDirective1',
148             func => \&MyDirective,
149             cmd_data => 'One',
150           },
151           {
152             name => 'MyDirective2',
153             func => \&MyDirective,
154             cmd_data => 'Two',
155           },
156         );
157         Apache2::Module::add(__PACKAGE__, \@directives);
158
159         sub MyDirective {
160           my ($self, $parms, $args) = @_;
161           my $info = $parms->info;
162         }
163
164       In this example $info will either be 'One' or 'Two' depending on
165       whether the directive was called as MyDirective1 or MyDirective2.
166
167   "method_is_limited"
168       Discover if a method is <Limit>ed in the current scope
169
170         $is_limited = $parms->method_is_limited($method);
171
172       obj: $parms ( "Apache2::CmdParms object" )
173       arg1: $method (string)
174           The name of the method to check for
175
176       ret: $is_limited ( boolean )
177       since: 2.0.00
178
179       For example, to check if the "GET" method is being "<Limit>"ed in the
180       current scope, do:
181
182         if ($parms->method_is_limited('GET') {
183             die "...";
184         }
185
186   "override"
187       Which allow-override bits are set ("AllowOverride" directive)
188
189         $override = $parms->override;
190
191       obj: $parms ( "Apache2::CmdParms object" )
192       ret: $override ( bitmask )
193           the allow-override bits bitmask, which can be tested against
194           "Apache2::Const :override constants".
195
196       since: 2.0.00
197
198       For example to check that the "AllowOverride"'s "AuthConfig" and
199       "FileInfo" options are enabled for this command, do:
200
201         use Apache2::Const -compile qw(:override);
202         $wanted = Apache2::Const::OR_AUTHCFG | Apache2::Const::OR_FILEINFO;
203         $masked = $parms->override & $wanted;
204         unless ($wanted == $masked) {
205             die "...";
206         }
207
208   "override_opts"
209       Which options are allowed to be overridden by ".htaccess" files. This
210       is set by "AllowOverride Options=...".
211
212         $override_opts = $parms->override_opts;
213
214       Enabling single options was introduced with Apache 2.2. For Apache 2.0
215       this function simply returns a bitmask with all options allowed.
216
217       obj: $parms ( "Apache2::CmdParms object" )
218       ret: $override_opts ( bitmask )
219           the bitmask, which can be tested against "Apache2::Const :options
220           constants".
221
222       since: 2.0.3
223
224   "path"
225       The current pathname/location/match of the block this command is in
226
227         $path = $parms->path;
228
229       obj: $parms ( "Apache2::CmdParms object" )
230       ret: $path ( string / "undef" )
231           If configuring for a block like <Location>, <LocationMatch>,
232           <Directory>, etc., the pathname part of that directive. Otherwise,
233           "undef" is returned.
234
235       since: 2.0.00
236
237       For example for a container block:
238
239         <Location /foo>
240         ...
241         </Location>
242
243       '/foo' will be returned.
244
245   "pool"
246       Pool associated with this command
247
248         $p = $parms->pool;
249
250       obj: $parms ( "Apache2::CmdParms object" )
251       ret: $p ( "APR::Pool object" )
252       since: 2.0.00
253
254   "server"
255       The (vhost) server this command was defined in httpd.conf
256
257         $s = $parms->server;
258
259       obj: $parms ( "Apache2::CmdParms object" )
260       ret: $s ( "Apache2::Server object" )
261       since: 2.0.00
262
263   "temp_pool"
264       Pool for scratch memory; persists during configuration, but destroyed
265       before the first request is served.
266
267         $temp_pool = $parms->temp_pool;
268
269       obj: $parms ( "Apache2::CmdParms object" )
270       ret: $temp_pool ( "APR::Pool object" )
271       since: 2.0.00
272
273       Most likely you shouldn't use this pool object, unless you know what
274       you are doing. Use "$parms->pool" instead.
275

Unsupported API

277       "Apache2::CmdParms" also provides auto-generated Perl interface for a
278       few other methods which aren't tested at the moment and therefore their
279       API is a subject to change. These methods will be finalized later as a
280       need arises. If you want to rely on any of the following methods please
281       contact the the mod_perl development mailing list so we can help each
282       other take the steps necessary to shift the method to an officially
283       supported API.
284
285   "context"
286       Get context containing pointers to modules' per-dir config structures.
287
288         $context = $parms->context;
289
290       obj: $parms ( "Apache2::CmdParms object" )
291       ret: $newval ( "Apache2::ConfVector object" )
292           Returns the commands' per-dir config structures
293
294       since: 2.0.00
295

Copyright

300       mod_perl 2.0 and its core modules are copyrighted under The Apache
301       Software License, Version 2.0.
302

Authors

304       The mod_perl development team and numerous contributors.
305
306
307
308perl v5.38.0                      2023-07-20   docs::api::Apache2::CmdParms(3)