Enable Mezzio Modules with laminas-component-installer

If you’re building packages for Mezzio, whether to use internally or as open source projects for the wider community, it’s likely that they will have a ConfigProvider class.

If you’re not familiar with them, ConfigProvider classes are where you can set a module’s configuration, such as routes, dependencies, and template paths. Here’s a short excerpt from one in a package that I’m currently building:

class ConfigProvider
{
    public function __invoke(): array
    {
        return [
            'dependencies' => $this->getDependencies(),
            'routes'       => $this->getRouteConfig(),
        ];
    }

    public function getDependencies(): array
    {
        return [
            'factories'  => [
                ForgotPasswordHandler::class                           => ForgotPasswordHandlerFactory::class,
                ForgotPasswordMiddleware::class                        => ForgotPasswordMiddlewareFactory::class,
    }

    public function getRouteConfig(): array
    {
        return [
            [
                'path'            => '/forgot-password',
                'middleware'      => ForgotPasswordHandler::class,
                'allowed_methods' => ['GET'],
            ],
            [
                'path'            => '/forgot-password',
                'middleware'      => ForgotPasswordMiddleware::class,
                'allowed_methods' => ['POST'],
            ],
        ];
    }
}

You can see that it calls two functions in the __invoke() magic method:

• getDependencies: which registers services with the application’s DI (Dependency Injection) container
• getRouteConfig: which registers routes with the application’s router

When enabled, the array returned from __invoke() will be combined with the rest of a Mezzio application’s configuration. But, ConfigProvider classes in your packages are not enabled by default.

How do your users enable them?

Well, you could tell them how to do so in your package’s documentation, or by printing the instructions to the terminal after running composer require on your package.

In short, you’d tell the user to add you’re module’s ConfigProvider to config/config.php in the array that initialises $aggregator; such as in the following example:

$aggregator = new ConfigAggregator([
    \SimpleUserManager\ConfigProvider::class,
    // ...remaining ConfigProvider classes.
]);

Yes, PhpStorm and other editors would reduce the effort required. But are users always going to remember to follow the instructions? Or, what if they made a typo and then their application threw an exception.

Perhaps I’m overthinking things, but these things can happen. And even though the issues aren’t your fault, some users might still form a negative impression of your package.

So, why have them enable the package by hand when you can automate it for them? How? By using laminas-component-installer!

What is laminas-component-installer?

If you’ve not heard of laminas-component-installer before, quoting it’s documentation:

[It’s a] Composer plugin for injecting modules and configuration providers into application configurations

By using it, when your package is installed, users will be asked if they wish to inject the configuration into their application’s configuration, such as with the example prompt below:

Please select which config file you wish to inject 'SimpleUserManager\ConfigProvider' into:
[0] Do not inject
[1] config/config.php
Make your selection (default is 1): 1

Remember this option for other packages of the same type? (Y/n) Y

If they answer “Y” to this prompt, laminas-component-installer will add it to config\config.php, which is the central configuration aggregator for Mezzio projects.

How do you integrate laminas-component-installer into a Mezzio package?

What’s truly awesome about it is that you don’t need to do much at all to use it. Start by adding it as a dependency of your package, whether by adding it manually to the require-dev element of you’re project’s composer.json file, as in the example below.

"require-dev": {
    "laminas/laminas-component-installer": "^3.5",
},

Or, run the command below instead:

composer require --dev laminas-component-installer

Regardless of the approach you take, you then need to add the following to composer.json:

"extra": {
    "laminas": {
        "config-provider": "<Your Project's Namespace>\\ConfigProvider"
    }
}

Under the extra.laminas.config-provider entry, provide the full namespace to your ConfigProvider. For example, in my current project, that’s:

"extra": {
    "laminas": {
        "config-provider": "SimpleUserManager\\ConfigProvider"
    }
}

After that, commit the change to your git repository, push it to GitHub, GitLab, etc. Then, when users run composer require for your package, they’ll see a variation on the prompt above, where answering “Y” will enable your package’s ConfigProvider class, enabling all of its configuration.

That’s why you should use laminas-component-installer with your Mezzio modules

Just to reiterate, you could enable a package’s ConfigProvider by hand. But with so many things to do in modern web applications, every little step that can be automated makes your users life that much simpler, and reduces the barriers to them using your packages.

If you’re not already, take advantage of laminas-component-installer to help make theirs, and your, life easier.

Module icons in the post’s main image were created by prettycons - Flaticon