A Beginner’s Introduction to Writing Modules in ProcessWire

ProcessWire modules enable you to extend functionality to the CMS admin, add new API integrations, and generally superpower your site. I often find myself reaching for the ProcessWire (PW) modules page to see if there is a pre-made solution to my current problem; and usually the answer is yes!

However, when you need to create something new, PW, like its templates, gives you the power of its API along with PHP.

In this tutorial we’re going to learn how to create and install modules, look at their requirements, and explain how to use PW hooks to add functionality to other functions within your site.

Installing

It's important to know how to install a module if you haven’t already done so. Following this process will show you where your module information and configuration will display, how to uninstall it, and which installed modules could be extended.

Upload module files to /site/modules/.
Within PW admin, in the top menu go to modules and click the button Refresh.
Now your new module will be listed and can be installed by clicking Install.

Creating a Module

Requirements

Let's start creating a new module. PW only needs a few things from your module:

a class name (e.g. HelloUserYouSaved)
the class should extend a PW basic class (e.g. Process, Wire or WireData)
your class should implement the “Module” class
and either a static getModuleInfo() method, or a ”ModuleName.info.php” file or a “ModuleName.info.json” within your module folder. This method offers up information about your module to be shown in the admin.

1	class HelloUserYouSaved extends WireData implements Module {
2	public static function getModuleInfo() {}
3	}

Through the extends WireData I have given my new module access to the PW API and methods inherited from WireData.

Our module is pretty boring right now, so let’s add some module info so that other users can see what it does.

getModuleInfo()

class HelloUserYouSaved extends WireData implements Module {

    public static function getModuleInfo() {
		return array(
			'title' => "HelloUserYouSaved",
			'version' => "0.0.1",
			'summary' => "HelloUserYouSaved shows messages after actions in PW",
			'author' => "Ben Byford",
			'href' => "https://github.com/benbyford/PW-starter-modules/tree/master/HelloUserYouSaved",
			'icon' => "bell",

			// use autoload if module is to be called each load, if it is only needed to setup something set to false
			'autoload' => true,
			'singular' => false,
			'requires' => "ProcessWire>=2.5",
		);
	}
}

For a full list of options, see module reference. summary , version and title are required, but it is also advisable to add your module requirements, singular (true if only one copy of this module is allowed per PW installation), and autoload (true to call module on every request).

Hooks

For all modules (even core modules) within PW, you can create hookable functions to allow other modules methods to be triggered on their use. For example, we can create a hook that triggers a new method ___helloMessage every time a page is saved with PW. You can tell what methods are hookable as they have three underscores before their name, which means our new method is also hookable by other modules.

public function init() {

    // add hook within class and point to custom function helloMessage
    $this->addHookAfter("Pages::save", $this, "helloMessage");
    Parent::init();
}

public function ___helloMessage($event) {
    
    // Get the soon to be saved page object from the given event
    $page = $event->arguments[0];
    
    // use message() to send hello alert to PW
    // alert will be shown after any admin page save.
    $this->message("Hello {$this->user->name}! You saved {$page->name}.");
}

In the code above, you can see how we add a hook to the core Pages module that triggers after the save method, which calls our ___helloMessage method. We have the option of adding hooks before or after the method is used: $this->addHookBefore() and $this->addHookAfter() respectively. As we are going to message the user after the page is saved, we are using the hook after variation.

Hooks are everywhere within PW, and after you’ve managed to get your head around using them, you can hook into most parts of the system to alter the default behaviour or trigger new behaviour. Here is a list of core modules and their hookable methods.

The complete source code for our “HelloUserYouSaved” module can be found on GitHub.

getModule()

You can also use modules to output data or markup into your templates. Any public function available within your module can be called upon in templates to output a result. For example, the module MarkupTwitterFeed can be used to output tweets by adding this code to your template:

1	$t = $modules->getModule('MarkupTwitterFeed');
2	echo $t->render();

The code above uses the getModule() method and stores the object so that the render() function can be used.

In this second module “FrontEndRender” a function named render() is implemented which we can use later in our templates to return Hello and a protected variable $name.

class FrontEndRender extends WireData implements Module {

    public static function getModuleInfo() {
		return array(
			'title' => 'FrontEndRender',
			'version' => 0.1,
			'summary' => "Outputs html and static variables to frontend",
			'author' => 'Ben Byford',
			'singular' => true,
			'href' => 'https://github.com/benbyford/PW-starter-modules'
		);
	}

	// protected variable only accessable within module
	protected $name = 'Ben';

	public function render(){
		return "Hello " . $this->name;
	}
}

We can echo the result anywhere in our template (e.g. our “_main.php” file) code by using:

1	$FrontEndRender = $modules->getModule('FrontEndRender');
2	echo '<h1>' . $FrontEndRender->render() . '</h1>';

The complete source code for our “FrontEndRender” module can be found on GitHub.

Wrapping Up

In this tutorial, we looked at installing and creating simple modules within ProcessWire. We also implemented a hook and rendered content to the front end using our custom modules.

There is much more to be said about modules so stay tuned for more PW module-making tutorials, and find more module information in the resources below.

Resources

PHP

Object-Oriented PHP for Beginners

Jason Lengstorf

24 Feb 2022

ProcessWire

Modules introduction on processwire.com
Modules docs on processwire.com
PW Hooks cheatsheet on processwire.com
GetModule() method on processwire.com
Module boilerplate creator on modules.pw