{eac}Doojigger derivatives are easy to create, custom WordPress plugins built from the {eac}Doojigger abstract classes and traits.

Your Directory Structure

Your plugin should be in a folder using your plugin class name. For example, if your plugin name is 'myAwesomePlugin', your plugin root folder should be named 'myAwesomePlugin'.

Within the 'myAwesomePlugin' folder, you should have a folder using your namespace. For example, if the namespace you're using is 'myAwesomeNamespace', you should have a folder named 'myAwesomePlugin/myAwesomeNamespace'.

Within the namespace folder, you must have a 'Plugin' folder to hold your plugin class file and you may have an 'Extensions' folder to hold any extensions.

myAwesomePlugin/
        myAwesomePlugin.php
        uninstall.php

        myAwesomeNamespace/
                Plugin
                    myAwesomePlugin.class.php
                Extensions
                    class.myAwesomeExtension.extension.php

Create your custom plugin loader

The loader class is a static class that is the WordPress primary plugin file and must contain the required WordPress headers; it will use the plugin_loader trait provided by {eac}Doojigger.

The file name should be {classname}.php (i.e. 'myAwesomePlugin.php') and should exist in the root folder by the same name.

/**
 * Plugin Name: My Awesome Plugin
 */
namespace myAwesomeNamespace
{
    class myAwesomePlugin
    {
        use \EarthAsylumConsulting\Traits\plugin_loader;

        protected static $plugin_detail =
            [
                'PluginFile'    => __FILE__,
                'NameSpace'     => __NAMESPACE__,
                'PluginClass'   => __NAMESPACE__.'\\Plugin\\myAwesomePlugin',
            ];
    } // myAwesomePlugin
} // namespace

namespace // global scope
{
    defined( 'ABSPATH' ) or exit;

    \myAwesomeNamespace\myAwesomePlugin::loadPlugin(true);
}

Create your custom plugin uninstaller

The uninstaller class is a static class used when your plugin is uninstalled; it will use the plugin_uninstall trait provided by {eac}Doojigger.

The file name should be uninstall.php and should exist in the root folder of your plugin.

namespace myAwesomeNamespace;

defined( 'WP_UNINSTALL_PLUGIN' ) or exit;

class myAwesomePlugin_uninstall
{
    use \EarthAsylumConsulting\Traits\plugin_uninstall;
}
myAwesomePlugin_uninstall::uninstall( basename(dirname(__FILE__)) );

Create your custom plugin class

The plugin class is where you'll do your work according to your requirements. But you can do so using the {eac}Doojigger framework.

The file name should be {classname}.class.php (i.e. 'myAwesomePlugin.class.php').

This file must exist in the 'Plugin' folder of your namespace folder (myAwesomePlugin/myAwesomeNamespace/Plugin/myAwesomePlugin.class.php).

If you are self-hosting your plugin and want to provide automatic updates, your plugin class must extend \EarthAsylumConsulting\abstract_context.

class myAwesomePlugin extends \EarthAsylumConsulting\abstract_context

If hosted on WP or you're not providing updates, extend \EarthAsylumConsulting\abstract_context_wp

class myAwesomePlugin extends \EarthAsylumConsulting\abstract_context_wp

The first, abstract_context, loads and uses the plugin_update trait. Your plugin header (in your loader) must include Plugin URI and Update URI

* Plugin URI: https://myawesomeserver.com/plugins/myAwesomePlugin/myAwesomePlugin.html
* Update URI: https://myawesomeserver.com/plugins/myAwesomePlugin/myAwesomePlugin.json

and you must provide the needed JSON and .zip files for updates on your server.

The first executable line in your plugin class must define the namespace as '{namespace}\Plugin'...

namespace myAwesomeNamespace\Plugin;

Then declare your class...

class myAwesomePlugin extends \EarthAsylumConsulting\abstract_context {...}

To incorporate any of the {eac}Doojigger traits, simply use them next...

use \EarthAsylumConsulting\Traits\standardOptions;

Then define your constructor method...

public function __construct(array $header) {...}

The $header variable passed to your constructor is the $plugin_detail variable defined in your plugin loader.

Within your constructor, you must call the parent constructor passing the $header array...

parent::__construct($header);

Then you can register any plugin options (option meta data), activation/deactivation hooks, install and version-update hooks...

$this->registerPluginOptions('plugin_settings', [ {option meta data} ]);

Once all plugins are loaded (when WordPress triggers the plugins_loaded filter), your plugin loader will...

• Call the loadAllExtensions() method.
• Fire the myAwesomePlugin_extensions_loaded action.
• Call the initialize() method.
• Fire the myAwesomePlugin_initialize action.
• Call the addActionsAndFilters() method.
• Call the addShortcodes() method.
• Fire the myAwesomePlugin_ready action.

Your plugin may define any methods or actions to respond to these.

If your plugin class implements the initialize(), the addActionsAndFilters() and/or the addShortcodes() methods, it must call the corresponding parent method.

Example Plugin Class

namespace myAwesomeNamespace\Plugin;

class myAwesomePlugin extends \EarthAsylumConsulting\abstract_context_wp
{
    use \EarthAsylumConsulting\Traits\standardOptions;

    public function __construct(array $header)
    {
        parent::__construct($header);

        $this->logAlways('version '.$this->getVersion().' '.wp_date('Y-m-d H:i:s',filemtime(__FILE__)),__CLASS__);

        if ($this->isSettingsPage())
        {
            // from standardOptions trait
            $this->registerPluginOptions('plugin_settings',$this->getStandardOptions(['siteEnvironment','adminSettingsMenu','uninstallOptions','backupOptions','restoreOptions']));
        }

        if (is_admin())
        {
            // When this plugin is activated
            register_activation_hook($header['PluginFile'],     array($this, 'admin_plugin_activated') );

            // When this plugin is deactivated
            register_deactivation_hook($header['PluginFile'],   array($this, 'admin_plugin_deactivated') );

            // When this plugin is installed ('myAwesomePlugin_version_installed')
            $this->add_action( 'version_installed',             array($this, 'admin_plugin_installed'), 10, 3);

            // When this plugin is updated ('myAwesomePlugin_version_updated')
            $this->add_action( 'version_updated',               array($this, 'admin_plugin_updated'), 10, 3 );
        }
    }

    public function initialize(): void
    {
        parent::initialize();
    }

    public function addActionsAndFilters(): void
    {
        parent::addActionsAndFilters();
    }

    public function addShortcodes(): void
    {
        parent::addShortcodes();
    }

    public function admin_plugin_activated()
    {
    }

    public function admin_plugin_deactivated()
    {
    }

    public function admin_plugin_installed($curVersion=null, $newVersion, $asNetworkAdmin)
    {
    }

    public function admin_plugin_updated($curVersion=null, $newVersion, $asNetworkAdmin)
    {
    }
}

Plugin Option Meta Data

Option Meta Data is an array of arrays defining options/settings that can be updated from the plugin's 'settings' page. Each option name is automatically prefixed with the plugin name (i.e. 'myAwesomePlugin').

An option is defined as:

'my_option_name'   => array(
                        'type'          =>  'type: {input type}',
                        'label'         =>  'label: {field label}',
                        'title'         =>  'title: information text/html to be displayed',
                        'options'       =>  array({option,...}),
                        'default'       =>  'default: {default option or value}',
                        'info'          =>  'info: Information/instructions',
                        'attributes'    =>  html attributes array ['name="value", name="value"']
                ),

See the 'readme.txt' file in the Extras/OptionMetaData folder for details on registering and using options in you plugin and extensions.

Filters and Shortcodes

{eac}Doojigger (and your derivative) provides a front-end filter and shortcode that gives access to (nearly) all public methods in your plugin.

The filter and shortcode name is the plugin class name ('myAwesomePlugin'). Arguments include:

• method='{methodName}', which is the name of any public method in your plugin (including those in the {eac}Doojigger abstract classes).
• args='...', to pass a list of arguments/values.
• default='...', to set a default value.
• index='...', to index an item from an array returned by your method.

Filter Examples:

  \apply_filters('myAwesomePlugin', null, [ method='getVariable' args='session_manager' ]); //  expecting session manager stored variable
  \apply_filters('myAwesomePlugin', null, [ method='_SERVER' args='server_name' ]);         //  expecting server name from $_SERVER
  \apply_filters('myAwesomePlugin', null, [ method='get_option' args='siteEnvironment' ]);  //  expecting siteEnvironment
  \apply_filters('myAwesomePlugin', null, [ option='siteEnvironment' ]);                    //  expecting siteEnvironment
  \apply_filters('myAwesomePlugin', null, [ option='blogdescription' ]);                    //  expecting WordPress blogdescription
  \apply_filters('myAwesomePlugin', null, [ option='woocommerce_cybersource_credit_card_settings' index='description' default='not installed' ]);   //  expecting cybersource description
  \apply_filters('myAwesomePlugin', null, [ bloginfo='name' ]);                             //  expecting WordPress Site Title

Shortcode Examples:

  ['myAwesomePlugin' method='getVariable' args='session_manager']   //  expecting session manager stored variable
  ['myAwesomePlugin' method='_SERVER' args='server_name']           //  expecting server name from $_SERVER
  ['myAwesomePlugin' method='get_option' args='siteEnvironment']    //  expecting siteEnvironment
  ['myAwesomePlugin' option='siteEnvironment']                      //  expecting siteEnvironment
  ['myAwesomePlugin' option='blogdescription']                      //  expecting WordPress blogdescription
  ['myAwesomePlugin' option='woocommerce_cybersource_credit_card_settings' index='description' default='not installed'] //  expecting cybersource description
  ['myAwesomePlugin' bloginfo='name' ]                              //  expecting WordPress Site Title

Arguments to the filter or shortcode may be passed as a comma-delimited string as 'args='.

  \apply_filters('myAwesomePlugin', null, [ method='myCoolMethod' args='arg1,arg2,...']);
  ['myAwesomePlugin' method='myCoolMethod' args='arg1,arg2,...']

Skeleton/Framework

There is a complete, functional skeleton of these examples in the 'Extras' folder of {eac}Doojigger that you can use to build your plugin by simply changing the namespace name, plugin name, and adding your own code.

1. My Awesome Plugin with My Awesome Extension

• When installed and registered, {eac}Doojigger installs an autoloader in the 'mu_plugins' folder. This autoloader manages the loading of all abstract classes, traits, interfaces, and extensions. There should never be a need to copy a .php file from {eac}Doojigger.