README

Code-enabled WordPress plugin loading package.

Installation

You can install the package via Composer:

composer require alleyinteractive/wp-plugin-loader

Usage

Load the package via Composer and use it like so:

use Alley\WP\WP_Plugin_Loader;

new WP_Plugin_Loader( [
	'plugin/plugin.php',
	'plugin-name-without-file',
] );

The plugin loader will load the specified plugins, be it files or folders under plugins/client-mu-plugins, and mark them as activated on the plugins screen. You can pass files or plugin folders that the package will attempt to determine the main plugin file from and load.

See APCu Caching for more information on caching.

Fluent Loading

The package supports a fluent API for loading plugins with the create() method:

use Alley\WP\WP_Plugin_Loader;

WP_Plugin_Loader::create()
	->add( 'plugin/plugin.php' )
	->add( [
		'plugin-name-without-file',
		'another-plugin',
	] )
	->load();

You can also use the when() method to conditionally load plugins:

use Alley\WP\WP_Plugin_Loader;

WP_Plugin_Loader::create()
	->add( 'plugin/plugin.php' )
	->when( fn () => 'production' !== wp_get_environment_type(), 'logger' )
	->load();

This pairs nicely with named arguments:

use Alley\WP\WP_Plugin_Loader;

WP_Plugin_Loader::create()
	->add( 'plugin/plugin.php' )
	->when(
		condition: fn () => 'production' !== wp_get_environment_type(),
		plugin: 'logger',
	)
	->load();

When using fluent loading you must call the load() method to load the plugins at the end of the chain.

Plugin Directories

Out of the box, the package will attempt to load your plugin from wp-content/plugins. When it is found, the package will attempt to load your plugin from wp-content/client-mu-plugins. For non-WordPress VIP sites, the plugin will also load plugins from wp-content/mu-plugins.

Preventing Activations

The package supports preventing activations of plugins via the plugins screen (useful to fully lock down the plugins enabled on site):

use Alley\WP\WP_Plugin_Loader;

( new WP_Plugin_Loader( [ ... ] )->prevent_activations();

Plugin activations will be prevented on the plugin screen as well as with a capability check.

APCu Caching

When a plugin is loaded by a directory name the package will attempt to determine the main plugin file from the directory. This can be a semi-expensive operation that can be cached with APCu. To enable caching, pass $cache to the constructor with a boolean or string prefix:

use Alley\WP\WP_Plugin_Loader;

new WP_Plugin_Loader( plugins: [ ... ], cache: true );

new WP_Plugin_Loader( plugins: [ ... ], cache: 'my-prefix' );

Note: caching will only be enabled if APCu is available.

Testing

Run composer test to run tests against PHPUnit and the PHP code in the plugin.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

This project is actively maintained by Alley Interactive. Like what you see? Come work with us.

• Sean Fisher
• All Contributors

License

The GNU General Public License (GPL) license. Please see License File for more information.