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.
Screen Shots
- My Awesome Plugin with My Awesome Extension
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.
Write a Reply or Comment