new(%opts)

my $finder = Module::Pluggable::Object->new(%opts);

Creates and returns a new finder object. All options are passed as a flat hash; they are stored on the object and consulted by "plugins". See "OPTIONS" below for the full list.

plugins

my @plugins = $finder->plugins;        # list of class names
my @objects = $finder->plugins(@args); # instances when 'instantiate' is set

The main entry point. Walks "search_path" across "search_dirs" (and @INC) and returns either a sorted list of fully-qualified package names or, if "instantiate" is set, a list of objects created by calling the named method on each plugin class.

Arguments passed to plugins() are forwarded to the "instantiate" method on each plugin class.

The full search is repeated on every call, which allows plugins installed after startup to be discovered at run time. If you do not need dynamic discovery and want to pay the I/O cost only once, memoize the result yourself:

our @PLUGINS;
sub plugins { @PLUGINS ||= shift->_finder->plugins }

search_directories(@dirs)

my @plugins = $finder->search_directories(@INC);

Iterates over @dirs and delegates to "search_paths" for each one. Normally called internally by "plugins", but exposed so subclasses can override the top-level directory loop.

search_paths($dir)

my @plugins = $finder->search_paths($dir);

For a single base directory, iterates over "/search_path" namespaces, locates ".pm" files under the corresponding subdirectory, converts file paths to package names, and calls "handle_finding_plugin" for each candidate.

Handles case-insensitive filesystems by reading the "package" declaration out of the file when the file name is all-lower or all-upper case.

handle_finding_plugin($plugin, \@plugins, $no_require)

$finder->handle_finding_plugin('MyApp::Plugin::Foo', \@plugins);

Called for each candidate package name discovered during the search. Applies the "only"/"except"/"min_depth"/"max_depth" filters, invokes "before_require" and "after_require" triggers, optionally "require"s the module, and pushes it onto "\@plugins" if everything succeeds.

Pass a true value for $no_require to skip the "require" step (used when the module is known to already be loaded, e.g. for inner packages).

find_files($search_path)

my @files = $finder->find_files($dir);

Recursively finds all files matching "file_regex" (default "qr/\.pm$/") under $dir using File::Find. Respects the "follow_symlinks" option.

handle_inc_hooks($search_path, @dirs)

my @plugins = $finder->handle_inc_hooks($path, @SEARCHDIR);

Handles the case where an entry in @INC is a blessed object with a files() method (as used by App::FatPacker and PAR). Calls files() on each such object, filters by $search_path, and delegates to "handle_finding_plugin".

handle_innerpackages($search_path)

my @plugins = $finder->handle_innerpackages('MyApp::Plugin');

Uses Devel::InnerPackage to find any package declared inside an already- loaded file whose name falls under $search_path. This is how "Something::Plugin::Bar" is discovered when it is defined inside Something/Plugin/Foo.pm. Set "inner => 0" to disable this behaviour.

package

The package name used to build the default "search_path". When using Module::Pluggable this is set automatically to the calling package. When using "Module::Pluggable::Object" directly you should set it explicitly.

search_path

An array ref (or a single string, which is promoted to an array ref) of namespace prefixes to search. Defaults to "["${package}::Plugin"]".

search_path => ['MyApp::Plugin', 'MyApp::Extension']

Alternatively, you can pass a hash ref where each key is a namespace prefix and each value is a hash ref of option overrides for that path. The per-path options are merged on top of the global options, so you only need to specify what differs.

search_path => {
    'MyApp::Plugin'    => { max_depth => 2 },
    'MyApp::Extension' => { max_depth => 3, instantiate => 'new' },
}

As another alternative, if you want plugins to be in a particular order, use an array ref of mixed plain strings and single-key hash refs. Order is preserved; only the hash ref entries carry per-path option overrides.

search_path => [
    'MyApp::Plugin',
    { 'MyApp::Extension' => { max_depth => 3, instantiate => 'new' } },
]

Results from all paths are combined and returned in a single list. Class names are deduplicated across paths; if any path uses "instantiate" its objects are included as-is alongside any class names from other paths.

search_dirs

An array ref (or a single string) of filesystem directories to search before @INC. Use this when plugins live outside the normal include path.

search_dirs => ['/opt/myapp/plugins']

search_dirs_strict

When true, only the directories in "search_dirs" are searched; @INC is ignored entirely. Requires "search_dirs" to also be set.

search_dirs_strict => 1

instantiate

Name of the method to call on each plugin class to create an instance. Typically 'new'. When set, plugins() returns a list of objects instead of class names. Arguments passed to plugins() are forwarded to this method.

instantiate => 'new'

require

When true, each plugin module is "require"d but not instantiated. Overrides "instantiate". Also enables inner-package discovery (see "inner").

require => 1

inner

Controls whether inner packages (secondary "package" declarations inside a single .pm file) are discovered.

• Defaults to true when "require" or "instantiate" is set.
• Set to 0 to disable even when "require" is set.

inner => 0

only

Restricts the returned plugins to those matching this value. May be:

• A string - only the exact named plugin is returned.
• An array ref of strings - only those exact plugins are returned.
• A compiled regex - only plugins whose name matches are returned.

only => qr/^MyApp::Plugin::Safe/

except

Excludes matching plugins from the results. Accepts the same forms as "only".

except => ['MyApp::Plugin::Broken', 'MyApp::Plugin::Deprecated']

min_depth / max_depth

Restrict discovery to plugins at a certain namespace depth (number of "::"-separated components).

For example, "MyApp::Plugin::Foo" has depth 3 and "MyApp::Plugin::Foo::Bar" has depth 4.

max_depth => 3   # only MyApp::Plugin::Foo, not MyApp::Plugin::Foo::Bar
min_depth => 4   # only MyApp::Plugin::Foo::Bar and deeper

file_regex

A compiled regex used to identify plugin files. Defaults to "qr/\.pm$/".

file_regex => qr/\.plugin$/

follow_symlinks

Whether to follow symbolic links when walking the filesystem. Defaults to 1 (follow symlinks) on all platforms except Windows with File::Find ≥ 1.39, where it defaults to 0 to preserve the historical behaviour.

follow_symlinks => 0

include_editor_junk

By default, files that look like editor artefacts are silently skipped:

• Files ending in "~" (Emacs / generic backup files).
• Files beginning with ".#" (Emacs lock files).
• Files matching "^[._].*\.s[a-w][a-z]$" (Vim swap files).

Set "include_editor_junk" to a true value to disable this filtering and include every file that matches "file_regex".

include_editor_junk => 1

force_search_all_paths

By default, when the module is loaded from inside a "blib/" tree (i.e. during "make test"), only @INC entries that themselves contain "blib" are searched. Set this option to search all of @INC regardless.

force_search_all_paths => 1

sort_results

Controls the order plugin names (or objects) are returned in. One of:

• 'alpha' (the default) - sorted alphabetically by package name.
• 'path' - returned in search-path discovery order: all plugins under the first "search_path" entry, then the second, and so on. Within a single path, order follows the underlying filesystem traversal.
• 0 - no sort is applied at all. Fastest option, for callers that will sort or otherwise order the results themselves.

sort_results => 'path'

before_require

before_require => sub { my ($plugin) = @_; ... }

Called with the plugin package name before it is "require"d. Return 0 to skip both the "require" and all subsequent steps for this plugin.

on_require_error

on_require_error => sub { my ($plugin, $err) = @_; ... }

Called when "require" raises an exception. The default handler "carp"s the error and returns 0 (dropping the plugin). Return a true value to keep the plugin in the list despite the error.

after_require

after_require => sub { my ($plugin) = @_; ... }

Called after a successful "require". Return 0 to exclude the plugin from results even though it has already been loaded.

before_instantiate

before_instantiate => sub { my ($plugin) = @_; ... }

Called with the plugin package name before the "instantiate" method is invoked. Return 0 to skip instantiation for this plugin.

on_instantiate_error

on_instantiate_error => sub { my ($plugin, $err) = @_; ... }

Called when the "instantiate" method raises an exception. The default handler "carp"s the error and returns 0.

after_instantiate

after_instantiate => sub { my ($plugin, $obj) = @_; return $obj }

Called after successful instantiation with the plugin name and the newly created object. The return value is used as the plugin entry in the results list; return a false value to discard the plugin entirely. Use this to wrap or decorate plugin objects transparently.