wpackio/enqueue

API to enqueue assets generated by @wpackio/scripts into your WordPress plugin or theme.

3.5.0 2023-01-14 07:33 UTC

Requires

• php: >=5.6

Requires (Dev)

• brain/monkey: ^2.2.0
• dealerdirect/phpcodesniffer-composer-installer: ^0.5
• giacocorsiglia/wordpress-stubs: ^4.9.5
• pcov/clobber: ^2.0
• phpcompatibility/phpcompatibility-wp: ^2.1.0
• phpunit/phpunit: ^7.3.0
• spatie/phpunit-snapshot-assertions: ^1.3.1
• wp-coding-standards/wpcs: ^2.2

MIT

• Swashata Ghosh

README

This is the PHP companion of @wpackio/scripts.

It gives you all the APIs you will need to properly consume assets generated from @wpackio/scripts from your WordPress plugins or themes.

Detailed Documentation

This README only covers the very basics and a quick start guide, without explaining the overall usage.

Please visit our official documentation site for detailed instruction.

Installation

Using Composer

We recommend using composer for using this library.

composer require wpackio/enqueue

Then in your plugin main file or functions.php file of your theme, load composer auto-loader.

<?php

// Require the composer autoload for getting conflict-free access to enqueue
require_once __DIR__ . '/vendor/autoload.php';

// Instantiate
$enqueue = new \WPackio\Enqueue( 'appName', 'outputPath', '1.0.0', 'plugin', __FILE__ );

Manual

If you do not wish to use composer, then download the file Enqueue.php.

Remove the namespace line namespace WPackio; and rename the classname from Enqueue to something less generic, like MyPluginEnqueue. This ensures conflict-free loading.

Then require the file in your plugin entry-point or functions.php file of your theme.

<?php

// Require the file yourself
require_once __DIR__ . '/inc/MyPluginEnqueue.php';

// Instantiate
$enqueue = new MyPluginEnqueue( 'appName', 'outputPath', '1.0.0', 'plugin', __FILE__ );

Getting Started

Which ever way, you choose to install, you have to make sure to instantiate the class early during the entry-point of your plugin or theme.

This ensures that we hava necessary javascript in our website frontend and admin end to make webpack code-splitting and dynamic import work.

A common pattern may look like this.

<?php
// Assuming this is the main plugin file.

// Require the composer autoload for getting conflict-free access to enqueue
require_once __DIR__ . '/vendor/autoload.php';

// Do stuff through this plugin
class MyPluginInit {
	/**
	 * @var \WPackio\Enqueue
	 */
	public $enqueue;

	public function __construct() {
		// It is important that we init the Enqueue class right at the plugin/theme load time
		$this->enqueue = new \WPackio\Enqueue( 'wpackplugin', 'dist', '1.0.0', 'plugin', __FILE__ );
		// Enqueue a few of our entry points
		add_action( 'wp_enqueue_scripts', [ $this, 'plugin_enqueue' ] );
	}


	public function plugin_enqueue() {
		$this->enqueue->enqueue( 'app', 'main', [] );
		$this->enqueue->enqueue( 'app', 'mobile', [] );
		$this->enqueue->enqueue( 'foo', 'main', [] );
	}
}


// Init
new MyPluginInit();

Default configuration when calling enqueue

[
	'js' => true,
	'css' => true,
	'js_dep' => [],
	'css_dep' => [],
	'in_footer' => true,
	'media' => 'all',
	'main_js_handle' => null,
	'runtime_js_handle' => null,
];

main_js_handle is added in 3.3 and can predictably set the handle of primary JavaScript file. Useful for translations etc.

runtime_js_handle is added in 3.4 and can predictably set the handle of the common runtime JavaScript. This is useful to localize/translate dependent script handles in the same files entry. By calling wp_set_script_translations on the runtime you can collectively enqueue translate json for all the dependencies on the entries.

For information on usage and API, please visit official documentation site wpack.io.

Avoid conflict in multiple WordPress Plugins

Always require the latest version of Wpackio\Enqueue. The autoloader is set to load only one instance and will not conflict with existing class.

However, if you want to load conflict free, kindly use Strauss.

Actions and Filters

Filter wpackio_print_public_path

Accepts 3 parameters:

• $publichPathUrl The URL that is used for the publicPath
• $appName Application Name
• $outputPath Output path relative to the root of this plugin/theme.

Using this you can dynamically change the public path that is used for code splitting. This can be used to change the public path to a CDN.

Example Code to replace all wpack.io public path with a cdn url

add_filter( 'wpackio_print_public_path', 'set_public_path_to_cdn' );

function set_public_path_to_cdn( $publichPathUrl ) {
	$home_url = get_home_url(); // WordPress home url
	$cdn_url = 'https://cdn.example.com'; // CDN url

	// replace wordpress home url with cdn url
	return str_replace($home_url, $cdn_url, $publichPathUrl);
}

Example Code to the change the public path url only for a specific instance of wpack.io

add_filter( 'wpackio_print_public_path', 'set_public_path_to_cdn', 10, 2 );

function set_public_path_to_cdn( $publichPathUrl, $appName ) {
	
	// check for our plugin
	if( 'myPlugin' !== $appName ) return $publichPathUrl;

	$home_url = get_home_url(); // WordPress home url
	$cdn_url = 'https://cdn.example.com'; // CDN url

	// replace WordPress home url with cdn url
	return str_replace($home_url, $cdn_url, $publichPathUrl);
}