Download the PHP package pinkcrab/enqueue without Composer

PinkCrab Enqueue

The PinkCrab Enqueue class allows for a clean and fluent alternative for enqueuing scripts and styles in WordPress.

To install

Version

Release 1.5.0

The above examples would enqueue the script and stylesheet using wp_enqueue_script() and wp_enqueue_style()

Features

Instantiation of \PinkCrab\Enqueue::class

You have 2 options when creating an instance of the Enqueue object.

When you call using the static methods script() or style(), the current instance is returned, allowing for chaining into a single call. Rather than doing it in the more verbose methods.

File Location

The URI to the defined js or css file can be defined here. This must be passed as a url and not the file path.

This is the same for both styles and scripts

Version

Like the underlying wp_enqueue_script() and wp_enqueue_style() function, we can define a verison number to our scripts. This can be done using the ver('1.2.2') method.

This is the same for both styles and scripts

However this can be frustrating while developing, so rather than using the current timestamp as a temp version. You can use the latest_version(), this grabs the last modified date from the defined script or style sheet, allowing reducing the frustrations of caching during development. While this is really handy during development, it should be changed to ->ver('1.2.2') when used in production.

This is the same for both styles and scripts

Dependencies

As with all wp_enqueue_script() and wp_enqueue_style() function, required dependencies can be called. This allows for your scripts and styles to be called in order.

This is the same for both styles and scripts

Localized Values

One of the most useful parts of of enqueuing scripts in WordPress is passing values form the server to your javascript files. Where as using the regular functions, this requires registering the style, localizing your data and then registering the script. While it works perfectly fine, it can be a bit on the verbose side.

The localize() method allows this all to be done within the single call.

This can only be called for scripts

Usage within js file (my-script.js)

Footer

By default all scripts are enqueued in the footer, but this can be changed if it needs to be called in the head. By calling either footer(false) or header()

This can only be called for scripts

Media

As with wp_enqueue_style() you can specify the media for which the sheet is defined for. Accepts all the same values as wp_enqueue_style()

This can only be called for styles

Attributes

It is possible (since v1.2.0) to add attributes and flags (value free attributes) to either script or style tags.

or

Async & Defer

Scripts can be marked as async or defer. As of v1.5.0 these forward to WordPress's wp_script_add_data( $handle, 'strategy', … ) API (WP 6.3+), which is dependency-chain aware — a deferred script waits for deferred deps to evaluate in order, rather than racing them via an unordered HTML attribute.

Calling defer() then async() (or vice versa) overwrites the strategy — a script can only have one. defer() / async() on a style is a no-op (style tags have no strategy concept).

Script Translations

Register the handle for i18n via wp_set_script_translations() so strings loaded with wp-i18n resolve from a .json file in the given path.

The path is optional — WP falls back to its language directory when omitted. Only meaningful on scripts; silent no-op on styles.

Inline Snippets

Append arbitrary inline JavaScript to the registered script handle via with_code(), which wraps wp_add_inline_script(). Multiple calls stack, and the optional second argument is the position ('before' or 'after', defaulting to 'after').

This is different from the existing inline() method, which replaces the src with the whole-file contents and inlines them. with_code() keeps the script loading normally from its URL and attaches short snippets around it.

Inline Styles

Same idea for styles — with_style() attaches inline CSS to a registered style handle via wp_add_inline_style().

Register Only

Register the asset with WP without enqueueing it. Useful when another script will reference this one via a dependency array, or when a block's block.json names the handle — the asset is available but doesn't emit on every page load.

Registration

Once your Enqueue object has been populated all you need to call register() for wp_enqueue_script() or wp_enqueue_style() to be called. You can either do all this inline (like the first example) or the Enqueue object can be populated and only called when required.

This is the same for both styles and scripts

Gutenberg / Block Editor

for_block

When registering scripts and styles for use with Gutenberg blocks declared in PHP, it is necessary to only register the assets — the block itself handles the enqueue. for_block() flags the Enqueue as register-only.

Block Editor Assets

For scripts/styles that should only load inside the WordPress admin block editor screens, use for_block_editor(). This defers the registration/enqueue flow to the enqueue_block_editor_assets hook, so you don't need to register the hook yourself.

Block Styles

Attach a stylesheet to a specific block name via wp_enqueue_block_style() so the CSS only loads on pages that render the block. Use for_block_style( $block_name ).

Block JSON

Register a block type directly from its block.json metadata directory. This short-circuits the normal script/style registration — block.json is the source of truth for the block's asset declarations, so the fluent API's src/deps/ver aren't used.

Public Methods

This obviously can be passed around between different classes/functions

Changelog

• 1.5.0 - Drop PHP 7.x, require PHP 8.0+. Modernise the tooling chain (PHPStan 2.x at level max, PHPUnit 8|9, WPCS 3.x, phpunit-polyfills widened to include v4, symfony/var-dumper + css-selector + dom-crawler unpinned). Replace the WP 5.9/6.0/6.1 workflows with the WP 6.6-6.9 matrix (PHP 8.0-8.4, mysql:8.4) using codecov/codecov-action@v4. Suppress the WP 6.8 wp_is_block_theme early-call notice in tests/wp-config.php. Guard latest_version() against null src (avoids PHP 8 TypeError). Narrow strtotime() argument when the Last-Modified header is returned as a list. Swap the trigger_error( …, E_USER_DEPRECATED ) in the legacy lastest_version() alias for _deprecated_function() so WP_UnitTestCase can track the deprecation properly. Drop the Codeclimate Maintainability badge from the README. Swap direct curl for wp_remote_head() in does_file_exist() / latest_version() so consumers can filter the HTTP layer and tests can mock via pre_http_request. New features: translations() wraps wp_set_script_translations(); with_code() attaches inline JS via wp_add_inline_script(); with_style() attaches inline CSS via wp_add_inline_style(); for_block_editor() defers registration to enqueue_block_editor_assets; for_block_style( $block_name ) wraps wp_enqueue_block_style(); register_only() registers without enqueueing; block_json() wraps register_block_type_from_metadata(). defer() / async() repurposed to use the dep-aware wp_script_add_data( $handle, 'strategy', … ) API (WP 6.3+) instead of splatting attributes through the script_loader_tag filter — runtime behaviour unchanged for consumers, rendering now handled by WP core.
• 1.4.0 - Dev dependency bumps to support WP 6.1.
• 1.3.0 - Updated for php8, includes setting of custom script types, renamed lastest_version() to latest_version() and set deprecation notice.
• 1.2.1 : Now supports block use. If defined for block, scripts and styles will only be registered, not enqueued.
• 1.2.0 : Added in Attribute and Flag support with helpers for Aysnc and Defer

Contributions

If you would like to make any suggestions or contributions to this little class, please feel free to submit a pull request or reach out to speak to me. at [email protected].

WordPress Core Functions

This package uses the following wp core functions. To use PHP Scoper, please add the following functions. ['wp_register_style', 'wp_enqueue_style', 'wp_register_script', 'wp_enqueue_script', 'wp_add_inline_script', 'wp_add_inline_style', 'wp_localize_script', 'wp_set_script_translations', 'wp_script_add_data', 'wp_enqueue_block_style', 'register_block_type_from_metadata', 'wp_remote_head', 'wp_remote_retrieve_response_code', 'wp_remote_retrieve_header', 'is_wp_error', '_deprecated_function']