How To: Using the {eac}Doojigger Installer

EarthAsylum Consulting WordPress eacDoojigger

Install a Must-Use plugin file, theme file, or other file using the WP_Filesystem API.

Document Header

Homepage:https://eacDoojigger.earthasylum.com/
Author:EarthAsylum Consulting
Last Updated:09-May-2025
Contributors:EarthAsylum Consulting, Kevin Burkholder Requires {eac}Doojigger:3.1.2
WordPress URI:https://wordpress.org/plugins/search/earthasylum/
GitHub URI:https://github.com/EarthAsylum/docs.eacDoojigger/wiki/

Using the eacDoojigger 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 a Doololly 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).

New in Version 2.6 shortcut actions to invoke the installer methods:

do_action('eacDoojigger_installer_invoke', $installAction, $installMethod, $installOptions, $onSuccess)
do_action('eacDoojigger_installer_install', $installOptions)
do_action('eacDoojigger_installer_update', $installOptions)
do_action('eacDoojigger_installer_uninstall', $installOptions)
do_action('eacDoojigger_installer_delete', $installOptions)

Top