Introducting the new n98-magerun module system

Published by Christian Münch on

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:

  MyNamespace: %module%/src

    - 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).

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

Example command:


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()
            ->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)
        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


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

Categories: Magerun


Pat Erler · September 8, 2014 at 09:56

what would be the best way, to install modules system wide?

    Christian Münch · September 8, 2014 at 10:36

    System wide modules must be placed in /usr/local/share/n98-magerun/modules on Unix/Linux machines.
    Windows users can put them into %windir%n98-magerunmodules

Rafael Corrêa Gomes ♛ · September 29, 2016 at 16:38

Thanks for sharing!

Add your own check to sys:check command | · July 3, 2014 at 15:29

[…] If you need a new checkgroup you can define a new one in your config. This can be done per project or as n98-magerun module. […]

Theme Refactoring | integer_net GmbH / EN · May 4, 2015 at 14:04

[…] you need the Magento command line utility n98-magerun and to install the magerun-addons as plugin (there are several ways to do so). The linked resources contain enough documentation, so I’ll spare you the details and dive […]

Leave a Reply

Avatar placeholder

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.