libapa...ective(3pm)

🌸 NAME 🌸

okay so <rainbow>Apache2::Directive</rainbow> — that's it, that's the name — and what it does is give you the Perl API for manipulating the Apache configuration tree. periodt 💅

also fyi this is a User Contributed Perl Documentation page, section 3pm, and the fancy header at the top squeezes the title down to libapa...ective(3pm), so if that's what you searched for, bestie, you're in the right place 🫶

---

✨ SYNOPSIS ✨

okay so first you load it, then you vibe around the tree. here's the whole shape of it:

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;
        }
    }
}

the walk there? chef's kiss. you go down to the first child, then sideways to the next, then back up and sideways again, until you run out of tree 👑 iykyk

---

🫶 DESCRIPTION 🫶

Apache2::Directive provides the Perl API for manipulating the Apache configuration tree. that's the entire description, no notes, it ate 🌈

---

👑 API 👑

Apache2::Directive gives you the following functions and/or methods — we are doing all of them, no skimming, no skipping, every since: 2.0.00 accounted for 💖

💅 args 💅

get the arguments for the current directive:

$args = $node->args();

• obj: $node ( an Apache2::Directive object )
• ret: $args ( string ) — the arguments are separated by a whitespace in the string.
• since: 2.0.00

so 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;

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

🎀 as_hash 🎀

get a hash representation of the configuration tree, in a format that's suitable for inclusion in <Perl> sections:

$config_hash = $conftree->as_hash();

• obj: $conftree ( an 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;

now $hash is:

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

look at it. all structured and gorgeous 😭

🦋 as_string 🦋

get a string representation of the configuration node, in httpd.conf format:

$string = $node->as_string();

• obj: $node ( an 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;

now $string is:

SetHandler perl-script
PerlHandler Test::Module

it gave config block, but as text. iconic 💜

🌟 conftree 🌟

get the root of the configuration tree:

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

• obj: Apache2::Directive ( class name )
• ret: $conftree ( an Apache2::Directive object )
• since: 2.0.00

this is your entry point, the main character of the whole tree, everything starts here 👑

🌸 directive 🌸

get the name of the directive in $node:

$name = $node->directive();

• obj: $node ( an 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 ( an 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;

now $filename is the full path to the httpd.conf that the VirtualHost was defined in. super handy when your config is spread over like forty includes 🙈

and ngl, if the directive was added with add_config(), the filename will be the path to the httpd.conf that triggered that Perl code.

🧚 first_child 🧚

get the first child node of this directive:

$child_node = $node->first_child;

• obj: $node ( an Apache2::Directive object )
• ret: $child_node ( an Apache2::Directive object ) — returns the first child node of $node, or 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 ( an 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 ( an 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
• since: 2.0.00

okay so the context thing is the plot twist here, keep up bestie:

if you call it with only the $directive value, this method returns all nodes from that directive. for example:

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

returns all nodes for Alias directives.

if you call it with an extra $args argument, it returns only the nodes where both the directive and the args matched. for example:

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

⭐ next ⭐

get the next directive node in the tree:

$next_node = $node->next();

• obj: $node ( an Apache2::Directive object )
• ret: $next_node ( an Apache2::Directive object ) — returns the next sibling of $node, or undef if there is none
• since: 2.0.00

💜 parent 💜

get the parent node of this directive:

$parent_node = $node->parent();

• obj: $node ( an Apache2::Directive object )
• ret: parent_node ( an Apache2::Directive object ) — returns the parent of $node, or undef if this node is the root node
• since: 2.0.00

the root node has no parent, it's giving orphan energy, it's fine, it's fine 😭

---

🍓 SEE ALSO 🍓

• mod_perl 2.0 documentation.

go read it, fr fr 📚

---

💜 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. absolute legends, every one of them 👑

---

and that's the page, bestie 💖 this beauty ships with perl v5.42.3 and it's dated 2026-08-20, so go forth and manipulate that configuration tree. slay 🦋✨