{eac}Doojigger: Plugin Derivatives

Document Header

Homepage:https://eacDoojigger.earthasylum.com/ Author:EarthAsylum Consulting Contributors:Kevin Burkholder Requires {eac}Doojigger:1.0.0

Custom plugin derivatives of {eac}Doojigger (build your own plugin using a strong, clean, foundation)

Description

{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.

Top
Screen Shots
  1. My Awesome Plugin with My Awesome Extension myAwesomePlugin
Top
Other Notes
  • 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.
Top

    Write a Reply or Comment

    Your email address will not be published.


    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>