The n98-magerun Module System

Since version 1.72.0, it has been possible to publish commands or configurations as a module. Modules offer an easy way to share configuration and commands directly within a project or development team without first having to adjust a configuration.

Module Structure

In its simplest form, a module consists of a directory and a configuration file named n98-magerun.yaml. The configuration file must be located directly in the module directory. Within the configuration file, you can change existing configurations or add new ones. So, nothing new really. The advantage of modules, however, is that n98-magerun searches for the corresponding modules within defined module base directories.

Example n98-magerun.yaml:

autoloaders:
  MyNamespace: %module%/src

commands:
  customCommands:
    - MyNamespace\FooCommand
    - MyNamespace\BarCommand

The placeholder %module% is replaced with the module's absolute path. It is not possible to place another module inside a module. Here we register our own PHP namespace in the n98-magerun autoloader and tell it where the source code is located. In this case, the directory

src
└── test-module 
    ├── n98-magerun.yaml 
    └── src 
        └── MyNamespace 
            ├── BarCommand.php 
            └── FooCommand.php

Example command:

<?php

namespace MyNamespace;

use N98\Magento\Command\AbstractMagentoCommand;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class FooCommand extends AbstractMagentoCommand
{
    protected function configure()
    {
        $this
            ->setName('mynamespace:foo')
            ->setDescription('Test command registered in a module')
        ;
    }

    /**
     * @param \Symfony\Component\Console\Input\InputInterface $input
     * @param \Symfony\Component\Console\Output\OutputInterface $output
     * @return int|void
     */
    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $this->detectMagento($output);
        if ($this->initMagento()) {
        // .. do something 
        }
    }
}

Where Are Modules Stored?

Currently, three directories are provided for modules. One global directory, one for the user, and one within a project. This keeps things flexible even when using modules.

• /usr/local/share/n98-magerun/modules
• ~/.n98-magerun/modules
• MAGENTO_ROOT/lib/n98-magerun/modules

The order of configuration processing is now as follows:

• [DIST] config.yaml inside the phar file
• [Module] Modules in the order listed above
• [System] Configuration from /etc/n98-magerun.yaml
• [User] ~/n98-magerun.yaml
• [Project] MAGENTO_ROOT/app/etc/n98-magerun.yaml

Tip: Integrate n98-magerun Commands Directly into a Magento Module

The new module directory under lib/n98-magerun/modules allows an n98-magerun module to be shipped directly with a Magento module.

Example Magento module "My_Foo":

├── app
│   ├── code
│   │   └── local
│   │       └── My
│   │           └── Foo
│   │               └── etc
│   │                   └── config.xml
│   └── etc
│       └── modules
│           └── My_Foo.xml
└── lib
    └── n98-magerun
        └── modules
            └── my-foo
                └── n98-magerun.yaml

The n98-magerun command can also be registered as usual through modman, for example. Installation through Composer with the Magento-Composer-Installer is therefore also possible.

Conclusion:

The new module system makes it possible to exchange modules quickly. This allows you to create your own ecosystem based on n98-magerun.