Download the PHP package themehybrid/hybrid-assets without Composer

Hybrid Assets

Asset (CSS/JS etc.) resolution for Hybrid Core.

Hybrid Assets gives themes and plugins a single, consistent API for resolving asset URLs, filesystem paths, dependencies, and cache-busting versions — with automatic support for child-theme overrides, wp-scripts .asset.php metadata, and Laravel Mix manifests.

Why

WordPress asset registration usually means hardcoding URLs, manually tracking filemtime() for cache busting, and writing bespoke logic every time a child theme needs to override a parent theme or plugin asset. Hybrid Assets handles all of that:

• One API for themes and plugins alike (path(), url(), assetUrl(), assetPath(), asset())
• Automatic inheritance (when the inherit param is true) — child theme → parent theme → plugin fallback chain
• Automatic versioning — reads wp-scripts .asset.php files or Laravel Mix mix-manifest.json, falling back to a content hash
• Dependency resolution — reads wp_enqueue_script/style dependency arrays straight out of .asset.php

Requirements

• PHP 8.2+
• Hybrid Core ^7.0
• Hybrid Tools ^2.0
• WordPress 7.0+

Installation

Register the service provider on your container:

This binds ParentTheme and ChildTheme as singletons, and Plugin as a fresh (non-shared) binding — each plugin carries its own config (plugin file, override directory, manifest settings), so instances can't be shared between consumers.

Setting up a resolver

AssetsServiceProvider registers the underlying ParentTheme / ChildTheme / Plugin classes, but you still bind your own named instance — configured for your theme or plugin's specific asset directory — in your provider's register() method.

In a theme

In a plugin

Binding key names (my-theme/assets, my-plugin/assets) are your choice — just keep them unique across the container and reuse the same string in your Facade accessor (see below).

Usage

Direct container access

Via a Facade (recommended)

Wrapping your bound instance in a Facade gives you a clean, static-style call site without losing testability. Define one per theme/plugin:

Then enqueue assets with it directly:

The same pattern applies to plugins — just point getFacadeAccessor() at your plugin's binding key:

Child-theme / plugin-override inheritance

Pass inherit: true as the second argument to check the inheritance chain first. This lets a child theme override a parent theme's asset, or a theme override a plugin's asset:

Laravel Mix support

If your build uses Laravel Mix instead of @wordpress/scripts, point Hybrid Assets at the manifest when you bind it:

Metadata resolution order is always: .asset.php → mix-manifest.json → content hash fallback.

Inline SVG

svg() resolves a file through the same path and inheritance rules as asset(), then renders its markup inline — useful for icons you want to style with CSS or animate:

Markup is sanitized by default against an allow-list vendored from an open WordPress core pull request (#12197). It strips scripts, event handlers, javascript: / data: URLs (in href and xlink:href), <animate> / <set>, and disallowed elements. Once core ships that sanitizer, this package will call core's instead. A file that is missing, unreadable, or contains no valid SVG renders as an empty string rather than throwing.

On WordPress 7.0, wp_kses() cannot keep attribute names that contain a colon, so xmlns:xlink is dropped and xlink:href is rewritten to href. Unsafe URLs are still removed. WordPress 7.1 keeps both.

Inheritance works as it does for asset():

Skip sanitization only for build-pipeline output you control:

How resolution works

Exceptions

All exceptions implement Hybrid\Assets\Contracts\AssetsException, so the whole package can be caught with one type.

Architecture

License

This project is licensed under the GNU GPL, version 2 or later.

2008 – 2026 © Theme Hybrid.