While a plugin is (in WordPress) some kind of functionality or tool, a package is a collection of at least one or more modules. When it comes to WordPress development, packages help to deal with certain kind of development topics. So does the package we developed and which we want to introduce today, as it’s available for free on GitHub. The WordPress composer package Inpsyde Assets allows to deal with scripts and styles in a WordPress site.

The WordPress Composer Package Inpsyde Assets

The package is an OOP wrapper and allows to register and enqueue scripts and styles in a WordPress site in different locations.

The minimum requirements to use this package are PHP 7+ and WordPress latest-2. In case you want to install the package for development, via Composer, Inpsyde Assets also requires:

  • phpunit/phpunit (BSD-3-Clause)
  • brain/monkey (MIT)
  • inpsyde/php-coding-standards

Simply install the package via Composer:

$ composer require inpsyde/assets

When using Assets in your theme or plugin, you can simply access the Inpsyde\Assets\AssetManager by hooking into the setup-hook.

$ composer require inpsyde/assets

When using Assets in your theme or plugin, you can simply access the Inpsyde\Assets\AssetManager by hooking into the setup-hook.

This way you can start registering your assets:

<?php
use Inpsyde\Assets\AssetManager;
use Inpsyde\Assets\Script;
use Inpsyde\Assets\Style;
use Inpsyde\Assets\Asset;


add_action( 
	AssetManager::ACTION_SETUP, 
	function(AssetManager $assetManager) {
	
		$assetManager->register(
			new Script('foo', 'foo.js'),
			new Style('foo', 'foo.css')
		);
	}
);

The AssetFactory

Instead of creating instances by hand, it’s sometimes easier to use configuration via array or file to manage your specific assets.

config/assets.php

<?php
use Inpsyde\Assets\Asset;
use Inpsyde\Assets\Script;
use Inpsyde\Assets\Style;

return [
    [
		'handle' => '',
		'url' => 'example.com/assets/foo.css',
		'location' => Asset::FRONTEND,
		'type' => Style::class
    ],
    [
		'handle' => 'bar',
		'url' => 'example.com/assets/bar.js',
		'location' => Asset::FRONTEND,
		'type' => Script::class
    ],
];

In your application you can create all assets from that file by using the Inpsyde\Assets\AssetFactory:

<?php
use Inpsyde\Assets\AssetManager;
use Inpsyde\Assets\AssetFactory;

add_action( 
	AssetManager::ACTION_SETUP, 
	function(AssetManager $assetManager) {
		$assetManager->register(
			...AssetFactory::createFromFile('config/assets.php')
		);
	}
);

Assets

There are two main classes delivered:

  • Inpsyde\Assets\Script – dealing with JavaScript-files.
  • Inpsyde\Assets\Style – dealing with CSS-files.

Each instance requires a string $handle, string $url, int $location and optionally a configuration via array $config.

Following configurations are available:

propertytypedefaultScriptStyledescription
dependenciesarray[]xxall defined depending handles
locationintfalls back to Asset::FRONTENDxxdepending on location of the Asset, it will be enqueued with different hooks
versionstring''xxversion of the given asset
enqueuebool/callabletruexxis the asset only registered or also enqueued
dataarray/callable[]xxadditional data assigned to the asset
filterscallable[][]xxan array of Inpsyde\ Assets\ OutputFilter or callable values to manipulate the output
handlerstringScript
Handler::class

or
Style
Handler::class
xxThe handler which will be used to register/enqueue the Asset
localizearray/callable[]xlocalized array of data attached to Script
inFooterbooltruexdefines if the current Script is printed in footer
mediastring'all'xtype of media for the Style
Asset locations

By default the package comes with predefined locations of assets:

consthooklocation
Asset::FRONTENDwp_enqueue_scriptsFrontend
Asset::BACKENDadmin_enqueue_scriptsBackend
Asset::LOGINlogin_enqueue_scriptswp-login.php
Asset::CUSTOMIZERcustomize_controls_enqueue_scriptsCustomizer

To avoid duplicated registration of Assets in different locations such as backend and frontend, it is possible to add multiple locations via bitwise operator | (OR).

Additional Information about WordPress Composer Package Inpsyde Assets

You can use some OutputFilters which are specified to manipulate the output of the Script via script_loader_tag and Style via style_loader_tag. Check out which OutputFilter Inpsyde Assets provides and, moreover, how to create your own filter in GitHub.

Questions?

If you have questions or feedback, simply leave a comment and we’ll answer. 🙂

Comments

  1. Christian Foellmann1

    Hi,

    I have one WP vs Composer question:
    If 2 different authors use this package in a release version of their plugin… It kills WP, right?

    And one question about limiting enqueuing:
    I like to limit assets to necessary pages as much as possible. Are you thinking about adding a scope for the enqueue?

    Cheers,
    Chris

    1. Christian Brückner2

      Howdy Chris,

      sry for the late response – was on vacation. 🙂

      1. Anything broken?
      It really depends, how you’re going to build your whole setup. Normally you’ll include the package via Composer autoloading and the package can be shipped multiple times, but – depending on how plugin authors are going to include the vendor/autoload.php-file – the classes of the package are only included once.

      Our normal setup to deploy whole websites works via build pipeline and by using WPStarter [1]. WPStarter allows to “build” the whole website – also including WordPress as dependency – via Composer. When deploying a new release of the website (including plugins, theme, external packages), Composer resolves all dependencies and checks if there is any kind of “miss-match” in versions. So in short: The website isn’t build when something is not correct and nothing is broken. 😉

      ——

      2. Conditional enqueue
      Yes it is possible to enqueue assets depending on conditions! As you can see in documentation for “Assets” [2] the “enqueue”-key can receive either a boolean or callable value. So what you can do is:


      [
      'handle' => 'foo',
      'url' => 'example.com/assets/foo.css',
      'location' => Asset::FRONTEND,
      'type' => Style::class
      'enqueue' => function(): bool
      {
      return is_archive() && is_page() /* and so on */;
      }
      ]

      You could also just pass the 'enqueue' => 'is_archive' or any other callable as string, since the package is checking for “is_callable”.

      [1] https://github.com/wecodemore/wpstarter/
      [2] https://github.com/inpsyde/assets/blob/master/docs/02%20-%20Assets.md

Leave a reply

Your email address will not be published. Required fields are marked *