stellarwp/installer

StellarWP plugin install/activation library.

1.1.1 2023-06-06 13:25 UTC

Requires

• php: >=7.2
• ext-json: *

Requires (Dev)

• automattic/vipwpcs: ^2.3
• codeception/module-asserts: ^1.0
• codeception/module-cli: ^1.0
• codeception/module-db: ^1.0
• codeception/module-filesystem: ^1.0
• codeception/module-phpbrowser: ^1.0
• codeception/module-webdriver: ^1.0
• codeception/util-universalframework: ^1.0
• dealerdirect/phpcodesniffer-composer-installer: ^0.7.2
• lucatume/wp-browser: ^3.1
• phpcompatibility/phpcompatibility-wp: *
• szepeviktor/phpstan-wordpress: ^1.1
• the-events-calendar/coding-standards: dev-master
• wp-coding-standards/wpcs: ^2.3

GPL-2.0-or-later

README

A library for installing / activating other plugins. Authored by the development team at StellarWP and provided free for the WordPress community.

• Installation
  • Handling text domains
    • If you are using Strauss from within your vendor/bin directory
    • If you are using Strauss as a .phar file
• Initialization
• Registering a plugin
  • Simple registration
  • Registration with download link
  • Registration with an action indicating that the plugin is active
• Rendering an install/activate button
  • Render a button
  • Get a button
  • Get or render a button and redirect
• PHP - Actions
• PHP - Filters
• JS - Actions

Installation

It's recommended that you install Schema as a project dependency via Composer:

composer require stellarwp/installer

We actually recommend that this library gets included in your project using Strauss.

Luckily, adding Strauss to your composer.json is only slightly more complicated than adding a typical dependency, so checkout our strauss docs.

Handling text domains

This library has strings that are run through WordPress translation functions. Because of this, there's an extra step that needs to be taken to ensure that the placeholder %TEXTDOMAIN% is replaced with your project's text domain.

If you are using Strauss as a .phar file (recommended)

"scripts": {
	"strauss": [
		"test -f ./bin/strauss.phar || curl -o bin/strauss.phar -L -C - https://github.com/BrianHenryIE/strauss/releases/download/0.13.0/strauss.phar",
		"vendor/stellarwp/installer/bin/set-domain domain=YOUR_PROJECTS_TEXT_DOMAIN",
		"@php bin/strauss.phar"
	]
}

If you are using Strauss from within your vendor/bin directory

"scripts": {
    "strauss": [
      "vendor/stellarwp/installer/bin/set-domain domain=YOUR_PROJECTS_TEXT_DOMAIN",
      "vendor/bin/strauss"
    ]
}

Initialization

During the plugins_loaded action, initialize the installer.

namespace StellarWP\Installer\Config;
namespace StellarWP\Installer\Installer;

add_action( 'plugins_loaded', function () {
	Config::set_hook_prefix( 'boomshakalaka' );
	Installer::init();
} );

Registering a plugin

Registering plugins for installation should be done during (or after) the plugins_loaded action.

$installer->register_plugin( $slug, $plugin_name, $download_link, $did_action );

Parameter	Type	Description
$slug	string	Required. A simple slug for referring to your plugin.
$plugin_name	string	Required. The plugin name. This should not be translated. It must match what is in the plugin header docblock.
$download_link	string	The plugin download link. If this is omitted, it is assumed that the URL will come from WordPress.org plugin repository.
$did_action	string	If provided, the action will be checked with did_action() to indicate that the plugin is active.

Simple registration

use StellarWP\Installer\Installer;

add_action( 'plugins_loaded', function () {
	$installer = Installer::get();
	$installer->register_plugin( 'event-tickets', 'Event Tickets' );
} );

Registration with download link

use StellarWP\Installer\Installer;

add_action( 'plugins_loaded', function () {
	$installer = Installer::get();
	$installer->register_plugin( 'event-tickets', 'Event Tickets', 'https://example.com/event-tickets.zip' );
} );

Registration with an action indicating that the plugin is active

use StellarWP\Installer\Installer;

add_action( 'plugins_loaded', function () {
	$installer = Installer::get();
	$installer->register_plugin( 'event-tickets', 'Event Tickets', null, 'event_tickets_plugin_loaded' );
} );

Rendering an install/activate button

Buttons are the main point of this library. You can get or render a button. When you do, the relevant JavaScript will be enqueued to hook the button up with admin-ajax.php.

Render a button

use StellarWP\Installer\Installer;

Installer::get()->render_plugin_button( 'event-tickets', 'install', 'Install Event Tickets' );

Get a button

use StellarWP\Installer\Installer;

Installer::get()->get_plugin_button( 'event-tickets', 'install', 'Install Event Tickets' );

Get or render a button and redirect

use StellarWP\Installer\Installer;

// Get it.
$button = Installer::get()->get_plugin_button( 'event-tickets', 'install', 'Install Event Tickets', $redirect_url );

// Or render it.
Installer::get()->render_plugin_button( 'event-tickets', 'install', 'Install Event Tickets', $redirect_url );

PHP - Actions

stellarwp/installer/{$hook_prefix}/deregister_plugin

Fired when a plugin is deregistgered.

Parameters: string $slug

stellarwp/installer/{$hook_prefix}/register_plugin

Fired after registering a plugin.

Parameters: string $slug, string $plugin_name, string $download_link = null, string $did_action = null

PHP - Filters

stellarwp/installer/{$hook_prefix}/activated_label

Filters the label used for the "activated" button.

Parameters: string $label, string $slug, StellarWP\Installer\Contracts\Handler $handler

Default: Activated!

use StellarWP\Installer;
$hook_prefix = Installer\Config::get_hook_prefix();

add_filter( "stellarwp/installer/{$hook_prefix}/activated_label", function ( $label, $slug, $handler ) {
	return 'Activated, yo.';
}, 10, 3 );

stellarwp/installer/{$hook_prefix}/activating_label

Filters the label used for the "activating" button.

Parameters: string $label, string $slug, StellarWP\Installer\Contracts\Handler $handler

Default: Activating...

use StellarWP\Installer;
$hook_prefix = Installer\Config::get_hook_prefix();

add_filter( "stellarwp/installer/{$hook_prefix}/activating_label", function ( $label, $slug, $handler ) {
	return 'BOOM! Activating...';
}, 10, 3 );

stellarwp/installer/{$hook_prefix}/busy_class

Filters the class used for the "busy" state.

Parameters: string $class

Default: is-busy

use StellarWP\Installer;
$hook_prefix = Installer\Config::get_hook_prefix();

add_filter( "stellarwp/installer/{$hook_prefix}/busy_class", function ( $class ) {
	return 'is-very-busy';
} );

stellarwp/installer/{$hook_prefix}/button_classes

Filters the classes used for the button.

Parameters: array $classes, string $slug, StellarWP\Installer\Contracts\Handler $handler

Default: An array of default namespaced classes.

use StellarWP\Installer;
$hook_prefix = Installer\Config::get_hook_prefix();

add_filter( "stellarwp/installer/{$hook_prefix}/button_classes", function ( $classes, $slug, $handler ) {
	$classes[] = 'is-primary';
	$classes[] = 'some-other-class';
	return $classes;
}, 10, 3 );

stellarwp/installer/{$hook_prefix}/button_id

Filters the button id attribute for the button.

Parameters: string $id, string $slug, StellarWP\Installer\Contracts\Handler $handler

Default: null

stellarwp/installer/{$hook_prefix}/download_url

Filters the download_url used for the installation of the plugin.

stellarwp/installer/{$hook_prefix}/get_permission

Filters the permissions used for the installation of the plugin.

stellarwp/installer/{$hook_prefix}/install_error_message

Filters the install error message.

stellarwp/installer/{$hook_prefix}/installed_label

Filters the label used for the "installed" button.

Parameters: string $label, string $slug, StellarWP\Installer\Contracts\Handler $handler

Default: Installed!

use StellarWP\Installer;
$hook_prefix = Installer\Config::get_hook_prefix();

add_filter( "stellarwp/installer/{$hook_prefix}/installed_label", function ( $label, $slug, $handler ) {
	return 'Installed, yo.';
}, 10, 3 );

stellarwp/installer/{$hook_prefix}/installing_label

Filter the label used for the "installing" button.

Parameters: string $label, string $slug, StellarWP\Installer\Contracts\Handler $handler

Default: Installing...

use StellarWP\Installer;
$hook_prefix = Installer\Config::get_hook_prefix();

add_filter( "stellarwp/installer/{$hook_prefix}/installing_label", function ( $label, $slug, $handler ) {
	return 'YAY! Installing...';
}, 10, 3 );

stellarwp/installer/{$hook_prefix}/nonce_name

The name of the nonce field that is used when interacting with an install/activate button.

stellarwp/installer/{$hook_prefix}/wordpress_org_data

Filters the data returned from the WordPress.org plugin repository.

JS - Actions

stellarwp_installer_{$hook_prefix}_error

Fires when an error occurs during the installation of a plugin.

wp.hooks.addAction( 'stellarwp_installer_HOOK_PREFIX_error', function( selector, slug, action, message, hookPrefix ) {
	alert( message );
} );

Acknowledgements

Props to the folks at The Events Calendar for the efforts on the initial release of this library.