---
name: "Apache2::Directive"
section: "3pm"
platform: "linux"
package: "libapache2-mod-perl2"
version: "2.0.13-2+b2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Apache2::Directive"
---

# Apache2::Directive(3pm)

Perl API for manipulating the Apache configuration tree

## NAME

Apache2::Directive - Perl API for manipulating the Apache configuration tree

## Synopsis

```
  use Apache2::Directive ();

  my $tree = Apache2::Directive::conftree();

  my $documentroot = $tree->lookup('DocumentRoot');

  my $vhost = $tree->lookup('VirtualHost', 'localhost:8000');
  my $servername = $vhost->{'ServerName'};

  use Data::Dumper;
  print Dumper $tree->as_hash;

  my $node = $tree;
  while ($node) {
      print $node->as_string;

      #do something with $node

      my $directive = $node->directive;
      my $args = $node->args;
      my $filename = $node->filename;
      my $line_num = $node->line_num;

      if (my $kid = $node->first_child) {
          $node = $kid;
      }
      elsif (my $next = $node->next) {
          $node = $next;
      }
      else {
          if (my $parent = $node->parent) {
              $node = $parent->next;
          }
          else {
              $node = undef;
          }
      }
  }
```

## Description

`"Apache2::Directive"` provides the Perl API for manipulating the Apache configuration tree

## API

`"Apache2::Directive"` provides the following functions and/or methods:

### "args"

Get the arguments for the current directive:

```
  $args = $node->args();
```

- obj: $node ( "Apache2::Directive object" )

  - ret: $args ( string )

  Arguments are separated by a whitespace in the string.

- since: 2.0.00

  For example, in *httpd.conf*:

```
  PerlSwitches -M/opt/lib -M/usr/local/lib -wT
```

And later:

```
  my $tree = Apache2::Directive::conftree();
  my $node = $tree->lookup('PerlSwitches');
  my $args = $node->args;
```

`$args` now contains the string "-M/opt/lib -M/usr/local/lib -wT"

### "as\_hash"

Get a hash representation of the configuration tree, in a format suitable for inclusion in \<Perl\> sections.

```
   $config_hash = $conftree->as_hash();
```

- obj: $conftree ( "Apache2::Directive object" )

  The config tree to stringify

- ret: $config\_hash ( HASH reference )

  - since: 2.0.00

  For example: in *httpd.conf*:

```
  <Location /test>
    SetHandler perl-script
    PerlHandler Test::Module
  </Location>
```

And later:

```
  my $tree = Apache2::Directive::conftree();
  my $node = $tree->lookup('Location', '/test/');
  my $hash = $node->as_hash;
```

`$hash` now is:

```
  {
    'SetHandler'  => 'perl-script',
    'PerlHandler' => 'Test::Module',
  }
```

### "as\_string"

Get a string representation of the configuration node, in *httpd.conf* format.

```
   $string = $node->as_string();
```

- obj: $node ( "Apache2::Directive object" )

  The config tree to stringify

- ret: $string ( string )

  - since: 2.0.00

  For example: in *httpd.conf*:

```
  <Location /test>
    SetHandler perl-script
    PerlHandler Test::Module
  </Location>
```

And later:

```
  my $tree = Apache2::Directive::conftree();
  my $node = $tree->lookup('Location', '/test/');
  my $string = $node->as_string;
```

`$string` is now:

```
  SetHandler perl-script
  PerlHandler Test::Module
```

### "conftree"

Get the root of the configuration tree:

```
  $conftree = Apache2::Directive::conftree();
```

- obj: "Apache2::Directive" ( class name )

  - ret: $conftree ( "Apache2::Directive object" )

  - since: 2.0.00

  ### "directive"

Get the name of the directive in `$node`:

```
  $name = $node->directive();
```

- obj: $node ( "Apache2::Directive object" )

  - ret: $name ( string )

  - since: 2.0.00

  ### "filename"

Get the *filename* the configuration node was created from:

```
  $filename = $node->filename();
```

- obj: $node ( "Apache2::Directive object" )

  - ret: $filename ( string )

  - since: 2.0.00

  For example:

```
  my $tree = Apache2::Directive::conftree();
  my $node = $tree->lookup('VirtualHost', 'example.com');
  my $filename = $node->filename;
```

`$filename` is now the full path to the *httpd.conf* that VirtualHost was defined in.

If the directive was added with  `add_config()`, the filename will be the path to the *httpd.conf* that trigerred that Perl code.

### "first\_child"

Get the first child node of this directive:

```
  $child_node = $node->first_child;
```

- obj: $node ( "Apache2::Directive object" )

  - ret: $child\_node ( "Apache2::Directive object" )

  Returns the first child node of `$node`, `"undef"` if there is none

- since: 2.0.00

  ### "line\_num"

Get the line number in a *filename* this node was created at:

```
  $lineno = $node->line_num();
```

- obj: $node ( "Apache2::Directive object" )

  - arg1: $lineno (integer)

  - since: 2.0.00

  ### "lookup"

Get the node(s) matching a certain value.

```
  $node  = $conftree->lookup($directive, $args);
  @nodes = $conftree->lookup($directive, $args);
```

- obj: $conftree ( "Apache2::Directive object" )

  The config tree to stringify

- arg1: $directive ( string )

  The name of the directive to search for

- opt arg2: "args" ( string )

  Optional args to the directive to filter for

- ret: $string ( string / ARRAY of HASH refs )

  In LIST context, it returns all matching nodes.

  In SCALAR context, it returns only the first matching node.

  If called with only `$directive` value, this method returns all nodes from that directive. For example:

  ```
    @Alias = $conftree->lookup('Alias');
  ```

  returns all nodes for `"Alias"` directives.

  If called with an extra `$args` argument, it returns only nodes where both the directive and the args matched. For example:

  ```
    $VHost = $tree->lookup('VirtualHost', '_default_:8000');
  ```

- since: 2.0.00

  ### "next"

Get the next directive node in the tree:

```
  $next_node = $node->next();
```

- obj: $node ( "Apache2::Directive object" )

  - ret: $next\_node ( "Apache2::Directive object" )

  Returns the next sibling of `$node`, `"undef"` if there is none

- since: 2.0.00

  ### "parent"

Get the parent node of this directive:

```
  $parent_node = $node->parent();
```

- obj: $node ( "Apache2::Directive object" )

  - ret: "parent\_node" ( "Apache2::Directive object" )

  Returns the parent of `$node`, `"undef"` if this node is the root node

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