Wp Asset Manager Laravel Package

Getting Started

Install and check your floor first. v2.0.0 raises the minimum to PHP 8.3 and WordPress 6.3. If you're still on 8.1/8.2 or an older WP, pin to the 1.x line before you touch anything else. Then:

composer require alleyinteractive/wp-asset-manager

If you had a stale composer.lock, re-run composer update — v2 adds an explicit dependency on alleyinteractive/composer-wordpress-autoloader. Previously it came in transitively via mantle-framework/testkit, which dropped it in 1.21.0; a fresh install without the update can leave the plugin's own classes unautoloadable and you'll get "class not found" errors that look like a broken package.

Look at the wiki, not the README. The API reference moved out of the README into the wiki. Anyone following an old blog post or the 1.x README will be reading signatures that have since changed — bookmark the wiki as the source of truth.

First use case. The mental model is closest to a Laravel/Vite asset pipeline with per-asset strategy control: you declare the asset, its dependencies, and how it should load, and the plugin prints it. The 30-second version:

am_enqueue_script( 'my-app', 'dist/app.js', [ 'react' ], '1.0.0', [
    'load_method' => 'defer',
] );

am_enqueue_style( 'my-app', 'dist/app.css', [], '1.0.0', [
    'load_method' => 'async',
] );

Then verify the output: the tags should carry defer/async and print in dependency order. If you're coming from wp_enqueue_script(), the key difference is that anything with a non-sync load method bypasses core's enqueue machinery entirely — which has real consequences covered below.

Implementation Patterns

Pass load methods in the options array, not as a bare string. v2.0.0 fixed am_modify_load_method() raising a TypeError when handed an array — the form the docs have always shown. Every am_* helper now accepts array|string consistently, so standardise on the array form across your codebase and you'll match the documented examples.

Retrofitting load methods onto existing enqueues. This is the workhorse pattern for third-party or legacy assets you don't want to re-register:

add_action( 'wp_enqueue_scripts', function () {
    am_modify_load_method( 'some-plugin-script', [ 'load_method' => 'defer' ] );
}, 20 );

On WP 6.3+ this writes the method back through wp_script_add_data() as core's strategy argument, which is only read at enqueue time — hence the priority-after-enqueue requirement. That path was broken in 1.x and is fixed in v2.0.0, so if you'd previously given up on am_modify_load_method() for async/defer, retest it.

Responsive image preloading. New in v2.0.0, am_preload() accepts imagesrcset, imagesizes, and fetchpriority:

am_preload( 'hero.jpg', [
    'as'            => 'image',
    'imagesrcset'   => 'hero-400.jpg 400w, hero-800.jpg 800w, hero-1600.jpg 1600w',
    'imagesizes'    => '100vw',
    'fetchpriority' => 'high',
] );

The imagesrcset/imagesizes pair is what makes preload actually useful for <img srcset> heroes — without it the browser preloads a URL the srcset algorithm may never pick, and you've paid for a wasted request plus a console warning. Pair exactly one fetchpriority="high" image with it; anything more and you've just told the browser everything is urgent.

Dependencies now work for printed assets. v2.0.0 fixed deps being ignored for assets the plugin prints itself (inline, async, defer). Those bypass wp_enqueue_* and so never hit core's dependency resolution; they're now topologically ordered — dependencies print first, transitively — while unrelated assets keep registration order. This means you can finally rely on deps for deferred bundles instead of manually sequencing hook priorities. It also means print order can change after upgrading: if you were accidentally depending on registration order to get a working build, that luck may run out, in a good way, but check your output.

Conditional loading. The condition key (typed as array|string per the PHPStan fix) is the place for "only load this on these screens" logic, keeping conditional assets out of the critical path rather than enqueuing and de-enqueuing.

SVG sprites. SVG_Sprite remains the tool for inline symbol sets. Note the contract corrections in v2.0.0: get_svg() returns the <svg> DOMElement (or null on failure, not a DOMDocument), and create_symbol() returns a pair or null. If you have code that trusted the old docblocks — or that destructures create_symbol() unconditionally — add a null guard. That missing guard is exactly the bug that produced "Trying to access array offset on value of type null" on every page.

Template tags are on the clock. The am_* template tags still work in 2.x but are formally deprecated for the next major. If you call them directly in theme templates, start moving to the enqueue helpers now — this is a cheap migration today and a forced one later.

Gotchas and Tips

The stylesheet defer change is the one that will bite you. defer for stylesheets is deprecated and now behaves as async: it hides nothing and starts the fetch immediately during HTML parsing, instead of after DOMContentLoaded. That's a real timing shift — stylesheets that used to arrive late now contend with your critical CSS and LCP image. Audit every am_enqueue_style() with 'load_method' => 'defer', and re-measure LCP and CLS on anything above the fold. The async-defer load method is gone entirely, and the bundled loadCSS library — archived upstream — is no longer shipped or auto-enqueued, so if you depended on it loading itself, you now need your own non-blocking CSS strategy (or just accept async).

Unrecognised load methods now shout. am_enqueue_script() and am_enqueue_style() call _doing_it_wrong() on an unknown method instead of silently falling back to sync. Good for catching typos like 'defered'; noisy if you passed a method you removed (async-defer, or defer on styles). Omitting the key entirely still selects the default quietly — so the fix for a spurious notice is to omit rather than pass a guess.

The text domain moved from am to wp-asset-manager. If you ship translations, use load_plugin_textdomain() overrides, or grep for the domain in your own tooling, this silently breaks them. Regenerate any .pot/.po files against the new domain and re-check that your strings still resolve.

Removed internals mean removed escape hatches. Scripts::$async_scripts, Scripts::add_to_async(), Scripts::add_attributes(), Scripts::disable_concat(), Scripts::manage_async(), Asset_Manager::$assets_by_dependency, Asset_Manager::$assets_manual, and Styles::$loadcss_added are all gone. These were the pre-6.3 async fallback plus some internal bookkeeping. Any custom code reading those properties — including debugging helpers or test fixtures — needs rewriting against core's strategy argument. Grep for them before you upgrade, not after.

Enqueue errors are capability-gated. Asset errors print for users with the am_view_asset_error capability. There was a fatal in the invalid_enqueue_function branch (double-error-handling through format_error()) — fixed in v2.0.0, but it's a reminder that a nonexistent enqueue function fails at render time in a capability-dependent way. Check as an admin first when debugging; a broken asset can look fine to anonymous visitors or vice versa.

Tooling: lean on the new static analysis. PHPStan level 9 plus the corrected type signatures (get_svg(), generate_asset_error(), asset_should_add(), the condition key) means extension code you write against the package now type-checks properly for the first time. Point your own PHPStan config at level 9 if you're extending the plugin — several previously-reported "bugs" in your integration may resolve to nothing more than the old wrong docblocks.

Ruleset and CI notes. phpcs.xml is now phpcs.xml.dist, so add a local phpcs.xml to override. The plugin deliberately excludes WordPress.NamingConventions.PrefixAllGlobals (the published am_ prefix is three characters, below WPCS 3.x's four-character minimum) and WordPress.WP.EnqueuedResources (printing <link>/<script> directly is the entire point of the async/defer methods). Don't "fix" either exclusion if you inherit this ruleset — you'll break the plugin's public API.