stellarwp / installer
StellarWP plugin install/activation library.
Installs: 250 998
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 16
Forks: 2
Open Issues: 2
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
This package is auto-updated.
Last update: 2024-10-27 20:44:03 UTC
README
A library for installing / activating other plugins. Authored by the development team at StellarWP and provided free for the WordPress community.
- Installation
- Initialization
- Registering a plugin
- Rendering an install/activate button
- 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 );
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.