Module interface and classes

ProcessWire needs basic information about each module. Provide it via one of:

1. Static getModuleInfo() method:

public static function getModuleInfo() {
    return [
        'title'    => 'Hello World',
        'version'  => 1,
        'summary'  => 'One sentence description.',
        'author'   => 'Your Name',
        'href'     => 'https://example.com/module-info',
        'autoload' => false,
        'singular' => true,
        'requires' => ['OtherModule>=1.0.0', 'PHP>=8.0', 'ProcessWire>=3.0.200'],
        'installs' => ['SubModuleA', 'SubModuleB'],
    ];
}

2. ModuleName.info.php file (populates $info array, same structure as above):

$info = [
    'title' => 'Hello World',
    'version' => 1,
    /* ... */
];

3. ModuleName.info.json file:

{
  "title": "Hello World",
  "version": 1
}

Should you use getModuleInfo() or ModuleName.info.php (or json)?

In cases where the module has PHP or ProcessWire version requirements, or other module dependencies in the requires module info property, it is preferable to use a ModuleName.info.php or ModuleName.info.json file rather than a static getModuleInfo() method. This is because with a ModuleName.info.php (or json) file, the dependencies can be determined before loading the actual module file.

For example, the CliModule interface was added in ProcessWire 3.0.259 — if a user tried to install a CliModule in a version of ProcessWire prior to that, they would get an "unknown class: CliModule" error as soon as ProcessWire reads the module file. Using a ModuleName.info.php (or json) file ensures that these dependencies can be determined and resolved before ProcessWire attempts to read the module file.

If a module does not need to populate anything to the requires module info property, then it is fine to use a static getModuleInfo() method.

Module info properties

autoload values

requires version syntax

May be an array…

'requires' => [
    'OtherModule>=2.0.0',    // module with minimum version
    'PHP>=8.1',              // PHP version
    'ProcessWire>=3.0.200',  // ProcessWire version
],

…or a selector string:

'requires' => 'OtherModule>=2.0.0, PHP>=8.1, ProcessWire>=3.0.259',

All methods are optional. ProcessWire calls them when present:

public function init() {
    // called after config populated — attach hooks here
    $this->addHookAfter('Pages::saved', $this, 'onPageSaved');
}

public function ready() {
    // autoload modules only — $page is available here
    if($this->wire()->page->template == 'admin') { ... }
}

public function ___install() {
    // create fields, templates, pages, etc.
    // throw WireException if install cannot proceed
}

public function ___uninstall() {
    // undo everything install() did
    // throw WireException if uninstall cannot proceed
}

public function ___upgrade($fromVersion, $toVersion) {
    // migrate data or settings between versions
}

When a module is instianted, the method call order is: __construct(), wired(), init() and ready() (when applicable).

Extend a base type instead of plain WireData when your module fits a recognized pattern. Base types set defaults for singular, autoload, and provide additional structure.

In addition, modules may implement these interfaces for optional behaviors:

Process modules

Process modules are admin applications accessed via a page in the admin tree. They respond to URL segments via execute*() methods:

<?php namespace ProcessWire;

class ProcessHello extends Process {

    public static function getModuleInfo() {
        return [
            'title'   => 'Hello',
            'version' => 1,
            'summary' => 'A simple Process module.',
            'page'    => ['name' => 'hello', 'parent' => 'setup', 'title' => 'Hello'],
            'nav' => [ // optional navigation for admin theme dropdowns:
                ['url' => '',       'label' => 'Hello', 'icon' => 'smile-o'],
                ['url' => 'world/', 'label' => 'World', 'icon' => 'globe'],
            ],
        ];
    }

    // Handles /setup/hello/  (default)
    public function ___execute() {
        return '<p>Hello! See the <a href="./world/">world</a></p>';
    }

    // Handles /setup/hello/world/
    public function ___executeWorld() {
        return '<p>Here is the world: 🌐</p>';
    }
}

The page info property causes ProcessWire to auto-create the admin page on install and remove it on uninstall. See wire/core/Module/Process/Process.php for the full Process API.

CliModule interface

Modules implementing CliModule expose commands runnable from the command line:

class MyModule extends WireData implements Module, CliModule {

    public static function getModuleInfo() {
        return [
            'title' => 'My Module',
            'version' => 1,
            'summary' => '...',
            'cli' => 'foobar'
        ];
    }

    // called via: php index.php foobar [args...]
    public function executeCli(array $args) {
        if(empty($args)) return;
        if($args[0] === 'run') {
            if(isset($args[1]) && $args[1] === '--dry-run') {
                echo "Preview of main task";
            } else {
                echo "Running main task";
            }
        } else if($args[0] === 'hi') {
            echo "Hello there!";
        }
    }

    public function getCliCommands() {
        return [
            'run' => 'Run the main task',
            'run --dry-run' => 'Preview without making changes',
            'hi' => 'Say hello',
        ];
    }
}