NAME

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

Synopsis

use Apache2::CmdParms ();
use Apache2::Module ();
use Apache2::Const -compile => qw(NOT_IN_LOCATION);

my @directives = (
  {
    name => 'MyDirective',
    cmd_data => 'some extra data',
  },
);

Apache2::Module::add(__PACKAGE__, \@directives);

sub MyDirective {
    my ($self, $parms, $args) = @_;

    # push config
    $parms->add_config(['ServerTokens off']);

    # this command's command object
    $cmd = $parms->cmd;

    # check the current command's context
    $error = $parms->check_cmd_context(Apache2::Const::NOT_IN_LOCATION);

    # this command's context
    $context = $parms->context;

    # this command's directive object
    $directive = $parms->directive;

    # the extra information passed thru cmd_data to
    # Apache2::Module::add()
    $info = $parms->info;

    # which methods are <Limit>ed ?
    $is_limited = $parms->method_is_limited('GET');

    # which allow-override bits are set
    $override = $parms->override;

    # which Options are allowed by AllowOverride (since Apache 2.2)
    $override = $parms->override_opts;

    # the path this command is being invoked in
    $path = $parms->path;

    # this command's pool
    $p = $parms->pool;

    # this command's configuration time pool
    $p = $parms->temp_pool;
}

Description

Apache2::CmdParms provides the Perl API for Apache command parameters object.

API

Apache2::CmdParms provides the following functions and/or methods:

`add_config`

Dynamically add Apache configuration at request processing runtime:

$parms->add_config($lines);

obj: $parms ( Apache2::CmdParms object )
arg1: $lines (ARRAY ref): An ARRAY reference containing configuration lines per element, without the new line terminators.
ret: no return value
since: 2.0.00

See also: $s->add_config, $r->add_config

`check_cmd_context`

Check the current command against a context bitmask of forbidden contexts.

$error = $parms->check_cmd_context($check);

obj: $parms ( Apache2::CmdParms object )
arg1: $check ( Apache2::Const :context constant ): the context to check against.
ret: $error ( string / undef ): If the context is forbidden, this method returns a textual description of why it was forbidden. If the context is permitted, this method returns undef.
since: 2.0.00

For example here is how to check whether a command is allowed in the <Location> container:

use Apache2::Const -compile qw(NOT_IN_LOCATION);
if (my $error = $parms->check_cmd_context(Apache2::Const::NOT_IN_LOCATION)) {
    die "directive ... not allowed in <Location> context"
}

`cmd`

This module's command information

$cmd = $parms->cmd();

obj: $parms ( Apache2::CmdParms object )
ret: $cmd ( Apache2::Command object )
since: 2.0.00

`directive`

This command's directive object in the configuration tree

$directive = $parms->directive;

obj: $parms ( Apache2::CmdParms object )
ret: $directive ( Apache2::Directive object ): The current directive node in the configuration tree
since: 2.0.00

`info`

The extra information passed through cmd_data in Apache2::Module::add().

$info = $parms->info;

obj: $parms ( Apache2::CmdParms object )
ret: $info ( string ): The string passed in cmd_data
since: 2.0.00

For example here is how to pass arbitrary information to a directive subroutine:

my @directives = (
  {
    name => 'MyDirective1',
    func => \&MyDirective,
    cmd_data => 'One',
  },
  {
    name => 'MyDirective2',
    func => \&MyDirective,
    cmd_data => 'Two',
  },
);
Apache2::Module::add(__PACKAGE__, \@directives);

sub MyDirective {
  my ($self, $parms, $args) = @_;
  my $info = $parms->info;
}

In this example $info will either be 'One' or 'Two' depending on whether the directive was called as MyDirective1 or MyDirective2.

`method_is_limited`

Discover if a method is <Limit>ed in the current scope

$is_limited = $parms->method_is_limited($method);

obj: $parms ( Apache2::CmdParms object )
arg1: $method (string): The name of the method to check for
ret: $is_limited ( boolean )
since: 2.0.00

For example, to check if the GET method is being <Limit>ed in the current scope, do:

if ($parms->method_is_limited('GET') {
    die "...";
}

`override`

Which allow-override bits are set (AllowOverride directive)

$override = $parms->override;

obj: $parms ( Apache2::CmdParms object )
ret: $override ( bitmask ): the allow-override bits bitmask, which can be tested against Apache2::Const :override constants.
since: 2.0.00

For example to check that the AllowOverride's AuthConfig and FileInfo options are enabled for this command, do:

use Apache2::Const -compile qw(:override);
$wanted = Apache2::Const::OR_AUTHCFG | Apache2::Const::OR_FILEINFO;
$masked = $parms->override & $wanted;
unless ($wanted == $masked) {
    die "...";
}

`override_opts`

Which options are allowed to be overridden by .htaccess files. This is set by AllowOverride Options=....

$override_opts = $parms->override_opts;

Enabling single options was introduced with Apache 2.2. For Apache 2.0 this function simply returns a bitmask with all options allowed.

obj: $parms ( Apache2::CmdParms object )
ret: $override_opts ( bitmask ): the bitmask, which can be tested against Apache2::Const :options constants.
since: 2.0.3

`path`

The current pathname/location/match of the block this command is in

$path = $parms->path;

obj: $parms ( Apache2::CmdParms object )
ret: $path ( string / undef ): If configuring for a block like <Location>, <LocationMatch>, <Directory>, etc., the pathname part of that directive. Otherwise, undef is returned.
since: 2.0.00

For example for a container block:

<Location /foo>
...
</Location>

'/foo' will be returned.

`pool`

Pool associated with this command

$p = $parms->pool;

obj: $parms ( Apache2::CmdParms object )
ret: $p ( APR::Pool object )
since: 2.0.00

`server`

The (vhost) server this command was defined in httpd.conf

$s = $parms->server;

obj: $parms ( Apache2::CmdParms object )
ret: $s ( Apache2::Server object )
since: 2.0.00

`temp_pool`

Pool for scratch memory; persists during configuration, but destroyed before the first request is served.

$temp_pool = $parms->temp_pool;

obj: $parms ( Apache2::CmdParms object )
ret: $temp_pool ( APR::Pool object )
since: 2.0.00

Most likely you shouldn't use this pool object, unless you know what you are doing. Use $parms->pool instead.

Unsupported API

Apache2::CmdParms also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

`context`

Get context containing pointers to modules' per-dir config structures.

$context = $parms->context;

obj: $parms ( Apache2::CmdParms object )
ret: $newval ( Apache2::ConfVector object ): Returns the commands' per-dir config structures
since: 2.0.00

Copyright

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

Authors

The mod_perl development team and numerous contributors.

To install mod_perl2, copy and paste the appropriate command in to your terminal.

cpanm

cpanm mod_perl2

CPAN shell

perl -MCPAN -e shell
install mod_perl2

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

Synopsis

Description

API

add_config

check_cmd_context

cmd

directive

info

method_is_limited

override

override_opts

path

pool

server

temp_pool