- NAME
- Synopsis
- Description
- API
  - add_config
  - check_cmd_context
  - cmd
  - directive
  - info
  - method_is_limited
  - override
  - override_opts
  - path
  - pool
  - server
  - temp_pool
- Unsupported API
  - context
- See Also
- Copyright
- Authors

# 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

# See Also

mod_perl 2.0 documentation.

# 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.