Introducting the new n98-magerun module system

Since version 1.72.0 n98-magerun offers you a new possibility to share your commands and configuration. Modules can be created in a easy way.
In the past it was hard to share own commands within a developer team. Every team member must manually add configuration to a config file.
Now it’s possible to manage the configuration in a single file inside the module which can be updates by a VCS like SVN or GIT.

Module Structure

A module in the simplest form exists as a single folder with a config file which must be named n98-magerun.yaml.
The config file must be placed directly in the module folder. If you have created some commands in the past you will see that the confiuguration
format is nearly the same. Nothing really new. The new big thing is that n98-magerun will search automatically for modules in some defined basse folders and merges all found config files.

Example n98-magerun.yaml:

autoloaders:
  MyNamespace: %module%/src

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

The placegolder %module% will be replaced with the filesystme path of the module. It’s not possible to place a module inside an other module.
In the example we register an own PHP namespace for the n98-magerun Autoloader and tell n98-magerun where it can find our new command code (src folder).

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 should I place my module?

Currently there are three basedirs available to place custom modules.

A global folder for the system

• /usr/local/share/n98-magerun/modules

A folder inside the user’s home dir.

• ~/.n98-magerun/modules

A folder inside the Magento installation

• MAGENTO_ROOT/lib/n98-magerun/modules

The order of config merging process of the complete n98-magerun tool is now the following:

• [DIST] config.yaml inside the phar file
• [Module-Level] found module config as descibed above
• [System-Level] config in /etc/n98-magerun.yaml
• [User-Level] ~/n98-magerun.yaml
• [Project-Level] MAGENTO_ROOT/app/etc/n98-magerun.yaml

Tip: Integrate your n98-magerun commands in a standard Magento module

With the new module folder in lib/n98-magerun/modules* you can deliver n98-magerun command with a Magento module.

Example Magento Modul “My_Foo”:

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

Conclusion

With the new module system you can build powerful infrastructures. It’s easy to create and share commands with other team members.

We wish happy coding! Your feedback is welcome.

You netz98 Team