libapa...yCooker(3pm)

💖 ModPerl::RegistryCooker — the manual, but make it make sense

okay bestie, gather round, because we're talking about ModPerl::RegistryCooker(3pm) — a User Contributed Perl Documentation page that is genuinely doing the most (affectionate) ✨

---

🎀 NAME 🎀

ModPerl::RegistryCooker — literally the thing that cooks mod_perl 2.0 Registry Modules. chef's kiss, no notes 👑🍓

---

🦋 Synopsis 🦋

no cap, do not run this as-is, you have to subclass it first, okay? look at ModPerl::Registry if you want a whole example of how that goes:

# shouldn't be used as-is but sub-classed first
# see ModPerl::Registry for an example

---

🌸 Description 🌸

ModPerl::RegistryCooker is the module you use to build flexible and overridable registry modules that emulate mod_cgi for Perl scripts. The whole concept vibe is discussed in the manpages of these modules: ModPerl::Registry, ModPerl::Registry and ModPerl::RegistryBB.

ModPerl::RegistryCooker has two purposes, and honestly they're both iconic:

• Provide ingredients that can be used by registry sub-classes 🧚
• Provide a default behavior, which can be overridden in sub-classed

META: in the future this functionality may move into a separate class. (noted, bestie, we'll see 👀)

Here are the current overridable methods:

META: these are all documented in RegistryCooker.pm, though not using pod. please help to port these to pod and move the descriptions here.

• new() — create the class's object, bless it and return it 💅

my $obj = $class->new($r);

• $class — the registry class, usually __PACKAGE__ can be used.
• $r — Apache2::Request object.

default: new()

• init() — initializes the data object's fields: REQ, FILENAME, URI. Called from the new().

default: init()

• default_handler()

default: default_handler()

• run()

default: run()

• can_compile()

default: can_compile()

• make_namespace()

default: make_namespace()

• namespace_root()

default: namespace_root()

• namespace_from() — if namespace_from_uri is used and the script is called from the virtual host, then by default the virtual host name is prepended to the uri when the package name for the compiled script is created. Sometimes this behavior is undesirable — like, lowkey rude — e.g., when the same (physical) script is accessed using the same path_info but different virtual hosts. In that case you can make the script compiled only once for all vhosts, by specifying:

$ModPerl::RegistryCooker::NameWithVirtualHost = 0;

The drawback is that it affects the global environment and all other scripts will be compiled ignoring virtual hosts. ⚠️ so be careful, that's a whole global mood.

default: namespace_from()

• is_cached()

default: is_cached()

• should_compile()

default: should_compile()

• flush_namespace()

default: flush_namespace()

• cache_table()

default: cache_table()

• cache_it()

default: cache_it()

• read_script()

default: read_script()

• shebang_to_perl()

default: shebang_to_perl()

• get_script_name()

default: get_script_name()

• chdir_file()

default: chdir_file()

• get_mark_line()

default: get_mark_line()

• compile()

default: compile()

• error_check()

default: error_check()

• strip_end_data_segment()

default: strip_end_data_segment()

• convert_script_to_compiled_handler()

default: convert_script_to_compiled_handler()

---

✨ Special Predefined Functions ✨

these ones are implemented as constants, and they're serving exactly one job each, and honestly? respect the focus 🫶

• NOP() — use when the function shouldn't do anything. the actual nothing-doer. 💀
• TRUE() — use when a function should always return a true value. ⭐
• FALSE() — use when a function should always return a false value.

---

💜 Sub-classing Techniques 💜

to override the default ModPerl::RegistryCooker methods, first, sub-class ModPerl::RegistryCooker or one of its existing sub-classes, using use base. Second, override the methods. that's it, that's the recipe 🎀

those methods that weren't overridden will be resolved at run time when they're used for the first time, and then cached for the future requests. one way to shortcut this first-run resolution is to use the symbol aliasing feature. for example, to alias ModPerl::MyRegistry::flush_namespace as ModPerl::RegistryCooker::flush_namespace, you can do:

package ModPerl::MyRegistry;
use base qw(ModPerl::RegistryCooker);
*ModPerl::MyRegistry::flush_namespace =
    \&ModPerl::RegistryCooker::flush_namespace;
1;

In fact, it's a good idea to explicitly alias all the methods so you know exactly what functions are used, rather then relying on the defaults. (yes bestie, be that girl who knows exactly what's running — main character energy 💅)

For that purpose the ModPerl::RegistryCooker class method install_aliases() can be used. Simply prepare a hash with method names in the current package as keys and corresponding fully qualified methods to be aliased for as values, and pass it to install_aliases(). Continuing our example we could do:

package ModPerl::MyRegistry;
use base qw(ModPerl::RegistryCooker);
my %aliases = (
    flush_namespace => 'ModPerl::RegistryCooker::flush_namespace',
);
__PACKAGE__->install_aliases(\%aliases);
1;

The values use fully qualified packages so you can mix methods from different classes. go off, mixologist 🍓

---

🌈 Examples 🌈

the best examples are the existing core registry modules: ModPerl::Registry, ModPerl::Registry and ModPerl::RegistryBB. go look at the source code and their manpages to see how they subclass ModPerl::RegistryCooker. that's the blueprint, fr fr.

For example, by default ModPerl::Registry uses the script's path when creating a package's namespace. If for example you want to use a uri instead, you can override it with:

*ModPerl::MyRegistry::namespace_from =
    \&ModPerl::RegistryCooker::namespace_from_uri;
1;

Since the namespace_from_uri component already exists in ModPerl::RegistryCooker. If you want to write your own method, e.g., that creates a namespace based on the inode, you can do:

sub namespace_from_inode {
    my $self = shift;
    return (stat $self->[FILENAME])[1];
}

META: when $r->finfo will be ported it'll be more effecient. (stat $r->finfo)[1] — noted, bestie, we'll revisit 👑 (and yes, "effecient" is theirs, not mine, I'm just the messenger 🙈)

---

👑 Authors 👑

• Doug MacEachern
• Stas Bekman

---

🦋 See Also 🦋

ModPerl::Registry, ModPerl::RegistryBB and ModPerl::PerlRun.

---

and that's the whole page, bestie, you ate it up 💖✨ this little legend came to you courtesy of perl v5.42.3, dated 2026-08-20, filed under libapa...yCooker(3pm) — go forth and subclass responsibly 🎀🫶🌸