Module Runner is a CLI script that is intended to help in module development. Module Runner supports loading a module directly from the file system or by specifying an existing module instance from a given database table. In either case the parameters can be loaded from disk overriding any database parameters.

One might be wondering just how this is applicable and I'm glad you asked. The primary use case was in developing a new module that replaced an existing module. When doing this the most important requirement is that the functionality remains the same from the old module to the new module. To help this there is a --out parameter which permits outputting the module HTML to a file. If your module is deterministic then this provides an easy way to compare the output from one run to another. This could be used in a testing framework to validate the correct output of a given module with a given set of parameters.

Another interesting use case is module specific performance analysis. This is particularly important when the exist module turns out to be a slight overload. In the test case, the module being debugged took 0.264 seconds to render and executed 122 queries. By using module runner we can gather authoratative statistics on performance instead of approximations. In particular we can not only see the module render time reduces but that more objective measures that impact upon performance are also reduced (e.g. there are less queries executed).

The script includes a help script which demonstrate the parameters:

Usage:  php cli/modulerunner.php --id <module ID> [options]
        php cli/modulerunner.php --name <module name> [options]

Options:
    --id <id>        The module ID from #__modules to load and render.
    --name <name>    The name of the module to render (e.g. mod_footer)
    --debug          Enable debug (sets JDEBUG)
    --queries        Display queries exeucted
    --profiles       Display profiles (implies --debug)
    --params <path>  Load parameters from a path (overrides DB for --id)
    --client <id>    The client ID to use for --id (defaults to 0, e.g. site)
    --help, -h       Display this message

Notes:
        URLs output will be incorrect unless the $live_site variable is
        set in your configuration.php file.

As noted, there are two main ways of running the command:

1) With a module ID from the #__modules table
2) With a module name mapping onto the file system

The first is useful for existing instances or situations where the parameters are complicated. The second is useful in development of a new module (or existing one) where the parameters are less complex.

Both options permit overriding the parameters by reading from disk a file with the parameters stored within it.

An example of a module being executed follows:

cli/modulerunner.php --name mod_community_fastmembers --params /tmp/latestmembers.json --out /tmp/latest.html --queries --profiles

In this case we're running a module named mod_community_fastmembers which is a fork of the standard mod_community_members module shipped in JomSocial but with the aim of making it perform better through refactoring. In the example there is a fixed parameter file with the JSON parameters and the output of the module is going to a given location. This particular run is also displaying the queries executed and also any profiling data that was captured. This provides a valuable tool and insight for module developers who are looking to fine tune their extension outside of the noise of the normal Joomla! ecosystem. It provides module specific query logs and profiling access without having to strip down a site instance to get access to the same information.