Plugin Manager

The plugin manager of laminas-filter is called "filter plugin manager" – Laminas\Filter\FilterPluginManager.

The filter plugin manager is a specialized service manager that provides access to filter classes. It is used to create and manage instances of filters, which are used to transform data. The filter plugin manager can be created using a service container which implements the PSR-11: Container interface.

Creating a Filter Plugin Manager

The following example shows how to create a filter plugin manager using laminas-servicemanager, the dependency injection container provided by Laminas:

$filterPluginManager = new Laminas\Filter\FilterPluginManager(
    new Laminas\ServiceManager\ServiceManager()
);

Retrieving Filters

Filters can be retrieved from the filter plugin manager using the get() method. The filter plugin manager will automatically create an instance of the requested filter.

Fetching a filter by its class name:

$filter = $filterPluginManager->get(Laminas\Filter\StringTrim::class);

Fetching a filter by its alias:

$filter = $filterPluginManager->get('stringtrim');
$filter = $filterPluginManager->get('stringTrim');
$filter = $filterPluginManager->get('StringTrim');

TIP: The filter plugin manager is not really necessary for all filters which are provided by laminas-filter, beside the filter chains. Because all filters can be created without external dependencies, directly by using the constructor. (The filter chains require the filter plugin manager as a dependency to create the filters they contain.)

Registering Custom Filters

Custom filters can be registered with the filter plugin manager using the configure method or by passing configuration to the constructor.

NOTE: The manager is based on the plugin manager of laminas-servicemanager and the configuration follows the exact same pattern as for a normal service manager of laminas-servicemanager.

Using the configure Method

The configure method accepts an array of configuration options:

$filterPluginManager = new Laminas\Filter\FilterPluginManager(
    new Laminas\ServiceManager\ServiceManager()
);
$filterPluginManager->configure([
    'factories' => [
        Album\Filter\ExampleFilter::class => Album\Filter\ExampleFilterFactory::class,
    ],
    'aliases' => [
        'examplefilter' => Album\Filter\ExampleFilter::class,
    ],
    'abstract_factories' => [],
    'delegators'         => [],
    // …
]);

Using the Constructor

The constructor of the filter plugin manager accepts the same array of configuration options:

$filterPluginManager = new Laminas\Filter\FilterPluginManager(
    new Laminas\ServiceManager\ServiceManager(),
    [
        'factories' => [
            Album\Filter\ExampleFilter::class => Album\Filter\ExampleFilterFactory::class,
        ],
        'aliases' => [
            'examplefilter' => Album\Filter\ExampleFilter::class,
        ],
        'abstract_factories' => [],
        'delegators'         => [],
        // …
    ]
);

Fetching the Registered Custom Filter

The filter plugin manager can create the custom filter by the related class name:

$filter = $filterPluginManager->get(ExampleFilter::class);

Or by its alias, if it has been registered:

$filter = $filterPluginManager->get('examplefilter');

Passing Options to the Custom Filter

The manager uses the factory Laminas\ServiceManager\Factory\InvokableFactory to instantiate the filter, and will also pass the options for the filter to the constructor. The build() method of the manager can be used for this purpose:

$filter = $filterPluginManager->build(
    ExampleFilter::class,
    [
        // Options for the filter as an associative array
    ]
);

Fetch a Custom Filter Without Registration

The filter plugin manager allows fetching custom filters without prior registration with the manager.

The following example creates a custom filter that does not require any dependencies:

final class ExampleFilter implements Laminas\Filter\FilterInterface
{
    public function filter(mixed $value): mixed
    {
        // …
    }
}

The filter plugin manager can create the custom filter by the related class name:

$filter = $filterPluginManager->get(ExampleFilter::class);

The manager uses also here the factory Laminas\ServiceManager\Factory\InvokableFactory to instantiate the filter.

WARNING: An alias for the custom filter is not automatically created. If an alias is to be used, it must be registered manually in the filter plugin manager configuration.

Filters Are Not Shared

Unlike other plugin managers, filters are not shared by the filter plugin manager:

$filterPluginManager->get(ExampleFilter::class) !== $filterPluginManager->get(ExampleFilter::class);

Why Is the Filter Plugin Manager Relevant?

The primary purpose of the filter plugin manager is to provide a single object that can retrieve any known filter, regardless of whether it has complex dependencies or not.
The manager is used in input filters of laminas-inputfilter, stand-alone or in forms of laminas-form. In both cases, the manager is used internally to create filters for the input filter.

The following form illustrates how the filters are defined for the input filter. The filters are automatically retrieved from the filter plugin manager by their class name or alias.

Learn More

• Plugin Managers in laminas-servicemanager
• Configuring the Service Manager
• Using Input Filters in Forms of laminas-form