Module class

Module is the primary PHP interface for module types in ProcessWire.

The Module interface doesn't actually require any specific methods, (other than the className() method) but is required as an interface to state your intention to ProcessWire that your class is to be used as a Module. As a result, all methods are optional, but including the Module interface is not. You must also provide a means by which ProcessWire can query information about your module. More on that below.

Implementing the Module interface

Below is how you indicate a PHP class is a ProcessWire Module:

<?php namespace ProcessWire;
class HelloWorld extends WireData implements Module {
  // your class implementation
}

Modules should either extend the WireData class, or if they are a predefined type already recognized by ProcessWire, they should extend the base class of that type (or another module based upon it). Base module types include:

• AdminTheme
• Fieldtype
• FileCompilerModule
• FileValidatorModule
• Inputfield
• ModuleJS
• PageAction
• Process
• Textformatter
• WireAction
• WireMail
• WireSessionHandler

Requirements for Modules

1. Must provide a means of getting information about the module. This can be with a static getModuleInfo() method, or with a ModuleName.info.php file or a ModuleName.info.json file.

2. Must provide a className() method that returns the module class name. All Wire derived objects already do this, so you don't have to provide it unless your Module does not descend from a ProcessWire class. We recommend that your modules extend the Wire or WireData class.

3. If you have a __construct() method, it must not require any particular arguments.

4. If your module is configurable, it must also fulfill the ConfigurableModule interface.

Optional methods

• __construct() - Called before module config is populated.

• init() - Called after module config is populated.

• ready() - Called after init(), after API ready. Note that ready() applies to 'autoload' modules only.

• install() - Called when module is installed.

• uninstall() - Called when module is uninstalled.

• upgrade($fromVersion, $toVersion) - Called on version change.

• isAutoload() - Returns a boolean indicating whether the module should be loaded at boot. Can also be specified as a property in module information.

• isSingular() - Returns a boolean indicating whether the module is limited to one instance or not. Can also be specified as a property in module information.

• getModuleInfo() - A static method that returns an array of module information.

These methods are outlined in more detail further down on this page.

Module Information

Modules must have some way to communicate information about themselves to ProcessWire. This is done by providing an associative array containing this module information. One of the following implementations is required:

1. getModuleInfo() static method in your module class that returns an array.
2. YourModuleClass.info.php file that populates an $info array.
3. YourModuleClass.info.json file that contains an info object.

Each of these are demonstrated below:

1) Static getModuleInfo() method:

public static function getModuleInfo() {
  return array(
    'title' => 'Your Module Title',
    'version' => 1,
    'author' => 'Your Name',
    'summary' => 'Description of what this module does and who made it.',
    'href' => 'http://www.domain.com/info/about/this/module/',
    'autoload' => false, // set to true if module should auto-load at boot
    'requires' => array(
       'HelloWorld>=1.0.1',
       'PHP>=5.4.1',
       'ProcessWire>=2.4.1'
    ),
    'installs' => array('Module1', 'Module2', 'Module3'),
    );
}

2) YourModuleClass.info.php file:
Your file should populate an $info variable with an array exactly like described for #1 above, i.e.

$info = array(
  'title' => 'Your Module Title',
  'version' => 1,
  // and so on, like the static version above
);

3) YourModuleClass.info.json file:
Your JSON file should contain nothing but an object/map of the module info:

{
  "title": "Your Module Title",
  "version": 1
}

Note: The example JSON above just shows "title" and "version", but you would likely add more than that as needed, like shown in the static version above.

Module information properties

Required info properties

• title (string): The module's title.

• version (int|string): An integer or string that indicates the version number.

• summary (string): Summary text of the module (1 sentence recommended).

Optional info properties

• href (string): URL to more information about the module.

• requires (array|string): Array or CSV string of module class names that are required by this module in order to install.

  • Requires Module version: If a particular version of the module is required, then specify an operator and version number after the module name, like this: "HelloWorld>=1.0.1".

  • Requires PHP version: If a particular version of PHP is required, then specify "PHP" as the module name followed by an operator and required version number, like this: "PHP>=5.6.0".

  • Requires ProcessWire version: If a particular version of ProcessWire is required, then specify ProcessWire followed by an operator and required version number, like this: "ProcessWire>=2.4.1".

• installs (array|string): Array or CSV string of module class names that this module will handle install and uninstall for. This causes ProcessWire's dependency checker to ignore them and it is assumed your module will handle them. If your module does not handle them, ProcessWire will automatically install/uninstall them immediately after your module.

• permanent (boolean): This property is intended for only for core modules. When true, a module cannot be uninstalled.

• permission (string): Name of permission required of a user before ProcessWire will load the module (for non-superusers). Note that ProcessWire will not install this permission if it doesn't yet exist. To have it installed automatically, see the permissions option below this.

• permissions (array): Array of permissions that ProcessWire will install (and uninstall) automatically. Permissions should be in the format: array('permission-name' => 'Permission description').

• icon (string): Optional icon name to represent this module. Currently uses font-awesome icon names. Omit the "fa-" part, leaving just the icon name.

• singular (boolean): Is only one instance of this module allowed? (default=auto-detect). This is good for any module that you want to eliminate the possibility of multiple instances running at once. For instance, modules that become API variables are typically singular, whereas something like an Inputfield module would not be singular. When not specified, modules that extend an existing base type typically inherit the singular setting from the module they extend.

• autoload (boolean|string|callable|int): Should this module load automatically at boot? (default=false). This is good for modules that attach hooks or that need to otherwise load on every single request. Autoload is typically specified as a boolean true or false. Below are the different ways autoload can be specified:

  • Boolean: Specify true or false to indicate the module should either always autoload (true) or never autoload (false).

  • Selector string: The module will be automatically loaded only if the current page matches the selector string. For example, a selector string of template=admin would mean the module will only autoload in the admin side of ProcessWire.

  • Callable function: The module will automatically load only if the given callable function returns true.

  • Integer: If given integer 2 or higher, it will autoload the module before other autoload modules (in /site/modules/). Higher numbers autoload before lower numbers.

• searchable (string): When present, indicates that module implements a search() method consistent with the SearchableModule interface. The value of the 'searchable' property should be the name that the search results are referred to, using ascii characters of a-z, 0-9, and underscore. See the SearchableModule interface in this file for more details.

Module Methods

__construct()

This method is called by PHP immediately when the module is instantiated, and before any configuration data has been populated to the module. This method must not have any required arguments. This method is a good place for populating default configuration values or any other initialization you want to occur before ProcessWire sees it or populates anything to it. Your construct method should not assume that the module will actually be executed, as ProcessWire may instantiate a module for informational reasons.

init()

This method is called after __construct() and after any configuration data has been populated to the module. It is called before the module is handed over to the requester. This is a good place to perform any initialization that requires configuration data and can be a good place to attach hooks.

ready()

This method is used only by autoload modules. It is called when the entire ProcessWire API is ready to use. This may be preferable to the init() method for autoload modules because they are loaded and init()'d at boot, when everything else is loading too. The ready() method is called once the boot has completed and all API variables are ready to use, but before any page has been rendered. This makes it an excellent place to attach hooks.

isSingular()

Indicates whether only one instance of a module is allowed to exist in memory. If this method is not present, it will be auto-determined based on module type. If it is provided in the module information array (discussed above) that will override this method.

This method exists primarily so that base module types may specify a singular state and have it automatically inherit to any modules extending the type. If you are not extending a base module type then you can implement this method, or you can provide it in your module info array.

A module that returns TRUE is referred to as a "singular" module, because there will never be any more than a single instance of the module running.

Return TRUE if this module is a single reusable instance, returning the same instance on every call from Modules. Return FALSE if this module should return a new instance on every call from Modules.

• Singular modules will have their instance active for the entire request after instantiated.
• Non-singular modules return a new instance on every $modules->get("YourModule") call.
• Modules that attach hooks are usually singular.
• Modules that may have multiple instances (like Inputfield modules) should _not_be singular.

If you are having trouble deciding whether to make your module singular or not, be sure to read the documentation below for the isAutoload() method, because if your module is 'autoload' then it's probably also 'singular'.

isAutoload()

Should this module be automatically loaded at boot? If this method is not present, it will be auto-determined based on module type. If it is provided in the module information array (discussed above) that will override this method.

This method exists primarily so that base module types may specify an autoload state and have it automatically inherit to any modules extending the type. If you are not extending a base module type then you can implement this method, or you can provide it in your module info array.

A module that returns TRUE is referred to as an "autoload" module, because it automatically loads as part of ProcessWire's boot process. Autoload modules load before PW attempts to handle the web request.

Return TRUE if this module is automatically loaded at runtime. Return FALSE if this module must be requested via $modules->get('ModuleName') method before it is loaded.

Modules that are intended to attach hooks in the application typically should be autoload because they listen in to classes rather than have classes call upon them. If they weren't autoloaded, then they might never get to attach their hooks.

Modules that shouldn't be autoload are those that may or may not be needed at runtime, for example Fieldtype and Inputfield modules.

As a side note, I can't think of any reason why a non-singular module would ever be autoload. The fact that an autoload module is automatically loaded as part of PW's boot process implies it's probably going to be the only instance running. So if you've decided to make your module 'autoload', then is safe to assume you've also decided your module will also be singular (if that helps anyone reading this).

install()

This method is called when the module is first installed. If implemented, install() methods typically are defined hookable as public function ___install().

The method should prepare the environment with anything else needed by the module, such as newly created fields, pages, templates, etc. or installation of other modules.

If the install() method determines that the module cannot be installed for some reason, it should throw a WireException.

uninstall()

This method is called when the module is uninstalled. If implemented, uninstall() methods typically are defined hookable as public function ___uninstall().

This method should undo everything done by the install() method, or undo anything created by the module, restoring the system back to the state that it was in before the module was installed.

If the uninstall() method determines that it cannot proceed for some reason, it should throw a WireException.

upgrade($fromVersion, $toVersion)

This method is called when a version change is detected. This method should make any adjustments needed to support the module from one version to another. The previous known version ($fromVersion) and new version ($toVersion) are provided as arguments.

If implemented, upgrade() methods typically are defined hookable as public function ___upgrade(...). If the upgrade cannot proceed for some reason, this method should throw a WireException.

Click any linked item for full usage details and examples. Hookable methods are indicated with the icon.