Table of Contents

• About the {eac}Doojigger File System Extension
  • Access the WordPress file system via FTP/SSH with secure, compatible file permissions.
• Using the {eac}Doojigger Installer
  • Install a Must-Use plugin file, theme file, or other file using the WP_Filesystem API.
• Using Conditional Traits in PHP
  • Conditionally load backend (or frontend) code using traits.
• Clone an {eac}Doojigger Extension
  • Use an {eac}Doojigger extension in your derivative plugin (myAwesomPlugin).
• Using administrator option field methods
  • Add input fields to your custom screens.
• Using administrator contextual help methods
  • Add contextual help to your custom screens.
• Validate Registration & Licensing
  • Simple methods for checking the license level of a registered plugin.

About the {eac}Doojigger File System Extension

To properly install extensions and create folders & files, {eac}Doojigger uses the WordPress file access sub-system - WP_Filesystem. This system provides access to the web server files using FTP (file transfer protocol), FTPS (FTP over ssl), or SSH (secure shell or SFTP).

These protocols create files and folders using your ftp user name rather than the default web server user name (e.g. "www"", "www-data", "nobody", "apache") which should maintain proper and secure file permissions.

WordPress uses the WP_Filesystem when installing updates, plugins, and themes. You have probably seen the "Connection Information" form when applying updates. Unlike WordPress, {eac}Doojigger retains your connection information, in a secure, encrypted state, to be used when needed. Your secure credentials will be used by WordPress so you never see the "Connection Information" form again.

{eac}Doojigger provides two methods for accessing the WP_Filesystem:

The first (load_wp_filesystem), will initiate the "Connection Information" form (if $useform is not false) when required and either return the file system object or false.

public function load_wp_filesystem($useForm = false, string $notice = '', array $args = [])

• $useForm (false) when truthy, prompt for credentials if needed
• $notice ('') display an 'admin notice' message before the form
• $args ([]) request_filesystem_credential arguments (override defaults)

The second (link_wp_filesystem), provides a standard WordPress administrator notice, if the "Connection Information" form is required, with a link to access that form. This is less intrusive then load_wp_filesystem() and always returns false unless and until the user clicks the link.

public function link_wp_filesystem($useForm = true, string $notice = '', array $args = [])

• $useForm (true) when truthy, display notice with link
• $notice ('') display an 'admin notice' message before the form
• $args ([]) request_filesystem_credential arguments (override defaults)

Examples:

Redirects to the "Connection Information" form so the user can enter their FTP credentials. If credentials are already available, returns the WP_Filesystem object in $fs.

$fs = $this->fs->load_wp_filesystem(true,
    '{...something...} requires WordPress file system access.'
);

Displays an admin notice at the top of an administrator page providing a link to the "Connection Information" form. If credentials are already available, returns the WP_Filesystem object in $fs.

$fs = $this->fs->link_wp_filesystem(true,
    '{...something...} requires WordPress file system access.'
);

Returns either false (we don't have FTP credentials), or the WP_Filesystem object.

$fs = $this->fs->load_wp_filesystem();

In all cases, $fs will either be false or the WP_Filesystem object...

if ($fs) {
    // we can now use WP_Filesystem methods
    $fs->copy('thisfile','thatfile');
}

Note that once FTP credentials are entered via the "Connection Information" form, {eac}Doojigger saves them (encrypted) so the form is never needed again. FTP credentials can also be added to wp-config.php so that the "Connection Information" form is not required.

Using the {eac}Doojigger Installer

The installer extension is primarily intended to install a PHP script into the WordPress "must use plugins" folder (WPMU_PLUGIN_DIR), however, it may be used to install files in any folder within the WordPress directory structure.

In it's simplest form, you create an array of options which define the installer parameters (source, destination) when invoking the installer...

$this->installer->invoke('install',false,
    'title'         => 'My Awesome MU Plugin',  // title, false=silent
    'sourcePath'    => dirname(__FILE__),       // from this directory (defults to plugin dir)
    'sourceFile'    => 'myawesomemu.class.php', // source file to copy
    'targetPath'    => WPMU_PLUGIN_DIR,         // destination folder (default to WPMU_PLUGIN_DIR)
    'targetFile'    => 'myawesomemu.php',       // destination file (defaults to sourceFile)
    'connectForm'   => true,                    // allow automatic redirect to file system connection form
);

• The first parameter ($action) is one of 'install', 'update', uninstall', or 'delete'. 'install' & 'update', as well as 'uninstall' and 'delete' do the same thing but display the action verb to the user, assumedly being more intuitive.

There are shortcuts for the first parameter:

$this->installer->install(...);
$this->installer->update(...);
$this->installer->uninstall(...);
$this->installer->delete(...);

• The second parameter ($installMethod) is used to pass an installer function used only if we must redirect to the file system "Connection Information" form. On return, this method will be called (and must be callable as a static method or an extension method). It is usually the method that originally invoked the installer, so if needed, it should be __METHOD__ or [__CLASS__,__FUNCTION__].

The only time this is needed is if you're doing some pre or post processing around the installer.

public static function my_installer() {
    $installOptions = array(...);
    // pre-process
    $this->installer->install(__METHOD__,$installOptions);
    // post-process
}

There are also actions that may accomplish the same ('eacDoojigger_pre_install' and 'eacDoojigger_post_install'), or the '$onSuccess' callback parameter (below).

More often than not, this parameter can be, and should be, set to false.

• The third parameter ($installOptions) is the array of installer parameters (shown above) defining what is to be installed and where.

title is used to display a notice to the user when the action is completed or may be false to suppress notices.

sourceFile may be a single file name or a wildcard to handle multiple files (in which case, targetFile is not used).

If the installer requires file system credentials, these installer parameters are saved, then we redirect to the "Connection Information" form, then back to the originating page to retrieve the parameters and restart the installer process.

• A fourth parameter ($onSuccess) may be used to set a callback called immediately after your file is successfully installed but before determining if the install is successful. So if your callback function returns false, the installed file(s) are removed and the installation fails.

public static function my_installer() {
    $installOptions = array(...);
    $this->installer->install(__METHOD__,$installOptions, function($action,$installOptions)
        {
            // do something after file is installed
            return true;
        }
    );
}

Installers can also be queued to be run sequentially, either when invoked in your code or automatically when navigating to another page.

$this->installer->enqueue($action,false,$installOptions_a);
$this->installer->enqueue($action,false,$installOptions_b);
$this->installer->invoke(); // or on the next page-load.

A real-world example using enqueue with an installer method...

$this->add_action( 'version_updated', array( $this, 'admin_plugin_updated' ), 10, 3 );

public function admin_plugin_updated($curVersion, $newVersion, $asNetworkAdmin)
{
    $this->installer->enqueue('update',[$this,'install_autoloader']);
    $this->installer->invoke(); // or on the next page-load.
}

public function install_autoloader($action='install'): void
{
    $this->installer->invoke($action,[__CLASS__,__FUNCTION__],
        [
            'title'         => 'The {eac}Doojigger Autoloader',
            'sourcePath'    => $this->pluginHeader('VendorDir').'/Utilities',
            'sourceFile'    => 'eacDoojiggerAutoloader.php',
            'targetFile'    => 'eacDoojiggerAutoloader.php',
            'return_url'    => remove_query_arg('fs'),  // force reload after install
        ],
        function($action,$installOptions): bool         // callback onSuccess
        {
            // do stuff after installing
            return true;
        }
    );
}

Because the install is enqueued, it is dequeued when invoked. When dequeued, the installer method (install_autoloader) is called and the update runs.

Another real-world example that installs a "must use" plugin with support scripts in a sub-folder...

$this->installer->enqueue($action,false,
    [
        'title'         => false,
        'sourcePath'    => $this->pluginHeader('VendorDir').'/Utilities',
        'sourceFile'    => '*.php',
        'targetPath'    => WPMU_PLUGIN_DIR.'/eacDoojiggerEnvironment',
    ]
);
$this->installer->invoke($action,false,
    [
        'title'         => 'The {eac}Doojigger Environment Switcher',
        'sourcePath'    => $this->pluginHeader('VendorDir').'/Utilities',
        'sourceFile'    => 'eacDoojiggerEnvironment.class.php',
        'targetFile'    => 'eacDoojiggerEnvironment.php',
    ]
);

The first action enqueues the install of a sub-folder (eacDoojiggerEnvironment) within the 'mu_plugins' folder. The second action installs the primary script (eacDoojiggerEnvironment.php) into the "mu_plugins" folder then dequeues and runs the first action (the invoke'd action runs immediately, before the enqueue'd action).

Using Conditional Traits in PHP

I've found that within {eac}Doojigger, extensions, and any plugin, that a substantial amount of code is dedicated to backend or administrator functions. This doesn't bode well on the frontend as all of this unneeded code is loaded.

To alleviate this, we can use make-shift conditional traits...

1. Create a small trait file: myAwesomeTraits.trait.php

   <?php
   namespace myAwesomeNamespace;
   
   if ( ! is_admin() )
   {
       trait myAwesomeTraits {}
   }
   else require "myAwesomeTraits.admin.php";

2. Create your administrator trait file: myAwesomeTraits.admin.php

   <?php
   namespace myAwesomeNamespace;
   
   trait myAwesomeTraits
   {
       // your administration methods
       public function myAwesomeAdmin()
       {
       }
   }

3. Include your trait file in your plugin or extension

   require "myAwesomeTraits.trait.php";
   
   class myAwesomePlugin extends \EarthAsylumConsulting\abstract_context
   {
       /**
        * @trait myAwesomeTraits, loads only admin methods
        */
       use \myAwesomeNamespace\myAwesomeTraits;
   }

Using this method you can control what code gets loaded for backend (or frontend) use.

Clone an {eac}Doojigger Extension

Let's say you want to use the session manager included with {eac}Doojigger as an extension to your own plugin (myAwesomePlugin).

Create session_manager.extension.class.php in your myAwesomePlugin Extensions folder:

namespace myAwesomeNamespace\Extensions;

if ( class_exists('\EarthAsylumConsulting\Extensions\session_extension') )
{
    return new \EarthAsylumConsulting\Extensions\session_extension($this);
}

This works for extensions included with {eac}Doojiger but what about extension plugins? Let's try eacMetaPixel to add Facebook tracking to your plugin...

(almost the same but the auto-loader may not know where to find the extension if it hasn't been loaded yet.)

Create metapixel.extension.php in your myAwesomePlugin Extensions folder:

namespace myAwesomeNamespace\Extensions;

if ( class_exists('\EarthAsylumConsulting\Extensions\metapixel_extension') )
{
    return new metapixel_extension($this);
}
if ( file_exists(WP_PLUGIN_DIR.'/eacmetapixel/Extensions/metapixel.extension.php') )
{
    return require(WP_PLUGIN_DIR.'/eacmetapixel/Extensions/metapixel.extension.php');
}

This will load the metapixel extension, if it is installed, whether or not it is activated.

In both, the extension will be loaded by and will extend your plugin. Extension settings will be added to your options page and those settings will be stored with your plugin settings, prefixed with your plugin name.

Using administrator option field methods

Creating custom post types or taxonomies?

There are several methods used by {eac}Doojigger to create the administrator options screens. These methods may also be used outside of the plugin settings page for which they were created.

Note: These examples should only be used when on your custom screen. You can ensure that by checking the current screen id: if (get_current_screen()->id !== 'edit-my-screen-id') return;

These html_input methods are made available by using the html_input_fields trait in your plugin.

use \EarthAsylumConsulting\Traits\html_input_fields;

A simple example is to first create an array of field definitions similar to the plugin and extension options (see {eac}Doojigger: Administrator Options)...

$myFormOptions =
[
        'registrar_name'        => array(
                            'type'      =>  'text',
                            'label'     =>  'Registrar Name',
                        ),
        'registrar_phone'       => array(
                            'type'      =>  'tel',
                            'label'     =>  'Registrar Telephone',
                        ),
        'registrar_contact'     => array(
                            'type'      =>  'email',
                            'label'     =>  'Registrar Support Email',
                        ),
        'registrar_web'     => array(
                            'type'      =>  'url',
                            'label'     =>  'Registrar Web Address',
                        ),
];

html_input_style()

To incorporate the css style declarations needed for the embedded html, use the html_input_style() method...

add_action( 'admin_enqueue_scripts', array($this, 'html_input_style') );

html_input_block()

Then, where you want the form fields displayed, add the grid container and each of the fields, including label and input elements, using the html_input_block() method...

echo "<div class='settings-grid-container'>\n";
foreach ($myFormOptions as $optionKey => $optionData)
{
    $optionValue = ?;   // get the current value for the field
    echo $this->html_input_block($optionKey, $optionData, $optionValue);
}
echo "</div>\n";

html_input_sanitize()

To sanitize these fields when your form is submitted, use the html_input_sanitize() method...

foreach ($myFormOptions as $optionKey => $optionData)
{
    if (array_key_exists($optionKey,$_POST) )
    {
        $value = $this->html_input_sanitize($_POST[$optionKey], $optionKey, $optionData);
        if ($_POST[$optionKey] == $value)
        {
            // input is valid (passed sanitization), do something with it
        }
        else
        {
            // input is invalid, let the user know
            $this->add_option_error($optionKey,
                sprintf("%s : The value entered does not meet the criteria for this field.",$optionData['label'])
            );
        }
    }
}

html_input_validate()

The html_input_validate method uses and calls the field's 'validate' callback method (if set).

foreach ($myFormOptions as $optionKey => $optionData)
{
    if (array_key_exists($optionKey,$_POST) )
    {
        $value = $this->html_input_validate($_POST[$optionKey], $optionKey, $optionData);
    }
}

html_input_section()

For a more advanced layout with multiple blocks or sections of input fields...

$myFormSections =
[
    'registrar_contact'     =>
    [
            'registrar_name'        => array(
                                'type'      =>  'text',
                                'label'     =>  'Registrar Name',
                            ),
            'registrar_phone'       => array(
                                'type'      =>  'tel',
                                'label'     =>  'Registrar Telephone',
                            ),
            'registrar_contact'     => array(
                                'type'      =>  'email',
                                'label'     =>  'Registrar Support Email',
                            ),
            'registrar_web'     => array(
                                'type'      =>  'url',
                                'label'     =>  'Registrar Web Address',
                            ),
    ],
    'registration_defaults' =>
    [
        // ...
    ],
    'license_limitations'   =>
    [
        // ...
    ],
];

Add the fields in each section with a section header and fieldset (html_input_section())...

foreach ($myFormSections as $groupName => $myFormOptions)
{
    echo $this->html_input_section($groupName, $myFormOptions);
    foreach ($myFormOptions as $optionKey => $optionData)
    {
        $optionValue = ?;   // get the current value for the field
        echo $this->html_input_block($optionKey, $optionData, $optionValue);
    }
    echo "</fieldset>\n";
    echo "</section>\n";
}

Then sanitize the fields from each section using html_input_sanitize() when the form is submitted...

foreach ($myFormSections as $groupName => $myFormOptions)
{
    foreach ($myFormOptions as $optionKey => $optionData)
    {
        if (array_key_exists($optionKey,$_POST) )
        {
            $value = $this->html_input_sanitize($_POST[$optionKey], $optionKey, $optionData);
            if ($_POST[$optionKey] == $value)
            {
                // input is valid (passed sanitization), do something with it
            }
            else
            {
                // input is invalid, let the user know
                $this->add_option_error($optionKey,
                    sprintf("%s : The value entered does not meet the criteria for this field.",$optionData['label'])
                );
            }
        }
    }
}

add_option_error()

The add_option_error(), add_option_warning(), add_option_info(), and add_option_success() methods are similar to the WordPress add_settings_error() function with a slightly more advanced API that allows administrator notifications to be added anywhere on the page (befor the footer) and to survive a page reload or redirect.

Convert vertical section headers to horizontal tabs

Easily change a long vertical page with multiple input field sections into a tab layout with each section as a tab.

First add an element with a class of 'tab-container' where you want the tabs...

<nav class='tab-container'></nav>

Next add a 'true' boolean to the html_input_style() method...

add_action( 'admin_enqueue_scripts', function()
    {
        $this->html_input_style(true);
    }
);

This will include the css and javascript needed for tab functionality.

Additionally, you can pass an element selector which will have its visibility style changed to 'visible'.

$this->html_input_style(true,'table.form-table');

Screen Shot

These examples where derived from the Software taxonomy custom taxonomy extension used by {eac}SoftwareRegistry.

Using administrator contextual help methods

Taking the examples above and adding contextual help when adding fields is very simple.

First, in your constructor, add something like this to render the help screen.

add_action( 'current_screen',       function($screen)
    {
        if ($screen->id == 'edit-' . 'my-awesome-screen')
        {
            $this->addPluginHelpTab('My Awesome Screen', $content, ['My Awesome Screen','open']);
            $this->plugin_help_render($screen);
        }
    }
);

Then where you render your fields, render the field-level help with html_input_help()

foreach ($myFormSections as $groupName => $myFormOptions)
{
    echo $this->html_input_section($groupName, $myFormOptions);
    foreach ($myFormOptions as $optionKey => $optionData)
    {
        $this->html_input_help('My Awesome Screen', $optionKey, $optionData);
        if ($optionData['type'] == 'help') continue;

        $optionValue = ?;   // get the current value for the field
        echo $this->html_input_block($optionKey, $optionData, $optionValue);
    }
    echo "</fieldset>\n";
    echo "</section>\n";
}

See Providing Contextual Help for more details.

Validate Registration & Licensing

Simple methods for checking the license level of a registered plugin that uses the {eac}SoftwareRegistry Distribution Kit

/**
 * is license L2 (basic) or better
 *
 * @return  bool
 */
public function isBasicLicense(): bool
{
    return $this->isRegistryValue('license', 'L2', 'ge');
}

/**
 * is license L3 (standard) or better
 *
 * @return  bool
 */
public function isStandardLicense(): bool
{
    return $this->isRegistryValue('license', 'L3', 'ge');
}

/**
 * is license L4 (professional) or better
 *
 * @return  bool
 */
public function isProfessionalLicense(): bool
{
    return $this->isRegistryValue('license', 'L4', 'ge');
}

/**
 * is license L5 (enterprise) or better
 *
 * @return  bool
 */
public function isEnterpriseLicense(): bool
{
    return $this->isRegistryValue('license', 'L5', 'ge');
}