Create a module

This chapter will show you how to create a custom module for Post Status Notifier.

Requirements

A module must consist of at least a directory containing a bootstrap.php file. The directory is mandatory, a single bootstrap.php file will not be accepted. The module directory must only contain alphanumerical characters, no whitespace or special characters.

This is the structure of a minimalistic module setup, a directory called “Example” containing a file named “bootstrap.php”.

Example
└ bootstrap.php

Module package

The final module must be packaged in a zip file to be able to upload it through the Module Manager. It must contain the folder, in this case “Example”, on the root level.

Module archive

The module bootstrap

Naming conventions

The module’s bootstrap.php file must contain a PHP class. This class must adhere to naming conventions. For example, if your module directory is called “Example”, your bootstrap class must be called “Example_Bootstrap”. If your module directory is called “MyAwesomeModule”, your bootstrap class must be called “MyAwesomeModule_Bootstrap” and so on.

Additionally the bootstrap class must extend “IfwPsn_Wp_Module_Bootstrap_Abstract”.

<?php
// Example
// └ bootstrap.php

class Example_Bootstrap extends IfwPsn_Wp_Module_Bootstrap_Abstract
{
    ...

<?php
// MyAwesomeModule
// └ bootstrap.php

class MyAwesomeModule_Bootstrap extends IfwPsn_Wp_Module_Bootstrap_Abstract
{
    ...

Mandatory properties

The bootstrap class must have a set of protected properties which provide information about the module:

  • _id

  • _name

  • _description

  • _textDomain

  • _version

  • _author

  • _authorHomepage

  • _homepage

  • _dependencies

_id

The module’s internal ID. Choose something unique as this ID may only be used by one module. If there are two modules with the same ID, only the first one in the loading procedure will win. For the Example module the ID could be “psn_mod_exm”. For MyAwesomeModule it could be “psn_mod_maw” or more verbose “psn_mod_myawesome”. The string for the ID is not limited but keep it short.

protected $_id = 'psn_mod_exm';

_name

The module’s name. It will be displayed in the Module Manager (see screenshot).

protected $_name = 'MyModule';
Module name

_description

The module’s description. It will be displayed in the Module Manager (see screenshot).

protected $_description = 'This is an example module';
Module description

_textDomain

The module’s text domain if it uses translation.

protected $_textDomain = 'psn_exm';

_version

The module’s version. It will be displayed in the Module Manager (see screenshot).

Module version 
protected $_version = '1.0';

_author

The module’s author name. It will be displayed in the Module Manager (see screenshot).

Module version 
protected $_author = 'Timo';

_authorHomepage

The module’s author homepage. It will be displayed in the Module Manager (see screenshot).

Module version 
protected $_authorHomepage = 'http://www.ifeelweb.de/';

_homepage

The module’s homepage. It will be displayed in the Module Manager (see screenshot).

Module version 
protected $_homepage = 'http://www.ifeelweb.de/wp-plugins/post-status-notifier/';

_dependencies

The module dependencies. An array of other module’s ID’s which should be loaded before this one loads. Modules should always load after the built-in premium module (psn_mod_prm) which activates PSN’s in premium mode.

protected $_dependencies = array('psn_mod_prm');

bootstrap method

The bootstrap class is required to have a method called “bootstrap”. It will be executed in the module loading process. This method is the starting point of each module.

<?php
class Example_Bootstrap extends IfwPsn_Wp_Module_Bootstrap_Abstract
{
    ...

    public function bootstrap()
    {
        // This is the starting point of a module. This method gets called when the module gets loaded.

        // Your magic code starts from here :)
    }

This a complete example of a module bootstrap class:

<?php
class Example_Bootstrap extends IfwPsn_Wp_Module_Bootstrap_Abstract
{
    /**
     * @var string
     */
    protected $_id = 'psn_mod_exm';

    /**
     * @var string
     */
    protected $_name = 'Example';

    /**
     * @var string
     */
    protected $_description = 'This is an example module';

    /**
     * @var string
     */
    protected $_textDomain = 'psn_exm';

    /**
     * @var string
     */
    protected $_version = '1.0';

    /**
     * @var string
     */
    protected $_author = 'Timo';

    /**
     * @var string
     */
    protected $_authorHomepage = 'http://www.ifeelweb.de/';

    /**
     * @var string
     */
    protected $_homepage = 'http://www.ifeelweb.de/wp-plugins/post-status-notifier/';

    /**
     * @var array
     */
    protected $_dependencies = array('psn_mod_prm');



    /**
     * The module's bootstrap method
     */
    public function bootstrap()
    {
        // This is the starting point of a module. This method gets called when the module gets loaded.
    }
}

On module activation

After a module got uploaded through the Module Manager and it was accepted, it will be listed under “Installed modules”.

Module activation

The bootstrap class features three methods which will get called on activation, deactivation and deletion of the module.

onActivate

The onActivate method will be called when a module gets activated by clicking the “Activate” link in the Module Manager. Here you can initialize the creation of a custom database table for example.

/**
 * Fires when module gets activated by the Module Manager
 */
public function onActivate()
{
}

onDeactivate

The onDeactivate method will be called when a module gets activated by clicking the “Deactivate” link in the Module Manager.

/**
 * Fires when custom modules get deactivated by the Module Manager
 */
public function onDeactivate()
{
}

onDelete

The onDelete method will be called when a module gets activated by clicking the “Delete” link in the Module Manager. Here you can initialize the deletion of all custom data the module stored while it was active.

/**
 * Fires when custom modules get deleted by the Module Manager
 */
public function onDelete()
{
}

On plugin activation

If the complete plugin gets deactivated and deleted, the module’s onDeactivate respectively onDelete methods will not get called. For this case you should also hook into the plugin’s deactivation and deletion routines. This is done by using the Installer. The Installer object is accessible from the bootstrap class through the Plugin Manager like this:

$this->_pm->getInstaller();

It features three methods to add your own logic:

addActivation

The addActivation method gets called when PSN gets activated in the WordPress plugin backend. It expects an object implementing the interface IfwPsn_Wp_Plugin_Installer_ActivationInterface.

// e.g. in your bootstrap file
$this->_pm->getInstaller()->addActivation( new Psn_Module_Example_Installer_Activation() );

Objects implementing the interface IfwPsn_Wp_Plugin_Installer_ActivationInterface must implement the public method execute. There you can place your custom activation code like in this example:

class Psn_Module_Example_Installer_Activation implements IfwPsn_Wp_Plugin_Installer_ActivationInterface
{
    /**
     * @param IfwPsn_Wp_Plugin_Manager $pm
     * @param bool $networkwide - true if WordPress multisite is activated
     * @return mixed|void
     */
    public function execute( IfwPsn_Wp_Plugin_Manager $pm, $networkwide = false )
    {
        // here you could for example create a new database table
    }
}

addDeactivation

The addDeactivation method gets called when PSN gets deactivated in the WordPress plugin backend. It expects an object implementing the interface Ifw_Wp_Plugin_Installer_DeactivationInterface.

// e.g. in your bootstrap file
$this->_pm->getInstaller()->addDeactivation( new Psn_Module_Example_Installer_Deactivation() );

Objects implementing the interface IfwPsn_Wp_Plugin_Installer_DeactivationInterface must implement the public method execute. There you can place your custom deactivation code like in this example:

class Psn_Module_Example_Installer_Deactivation implements IfwPsn_Wp_Plugin_Installer_DeactivationInterface
{
    /**
     * @param IfwPsn_Wp_Plugin_Manager $pm
     * @param bool $networkwide - true if WordPress multisite is activated
     * @return mixed|void
     */
    public function execute( IfwPsn_Wp_Plugin_Manager $pm, $networkwide = false )
    {
        // if you want to execute code when the plugin gets deactivated, place it here
    }
}

addUninstall

The addUninstall method gets called when PSN gets deleted in the WordPress plugin backend. It expects an object implementing the interface Ifw_Wp_Plugin_Installer_UninstallInterface.

// e.g. in your bootstrap file
$this->_pm->getInstaller()->addUninstall( new Psn_Module_Example_Installer_Uninstall() );

Objects implementing the interface IfwPsn_Wp_Plugin_Installer_UninstallInterface must implement the public static method execute. There you can place your custom uninstall code like in this example:

class Psn_Module_Example_Installer_Uninstall implements IfwPsn_Wp_Plugin_Installer_UninstallInterface
{
    /**
     * @param IfwPsn_Wp_Plugin_Manager|null $pm
     * @return mixed|void
     */
    public static function execute($pm)
    {
        // for example remove database tables if the plugin gets deleted

        if (IfwPsn_Wp_Proxy_Blog::isMultisite()) {

            // on multisite installation

        } else {

            // on single blog installation
        }
    }
}