Mantle Framework Laravel Package

Product Decisions This Supports

• Build vs. buy for WordPress + Laravel hybrid stacks. This package is the integration layer that lets a team use Laravel-style conventions (Blade views, service container, models, routing, asset handling) inside WordPress. Adopting it is really a decision to standardize on Alley's opinionated WP framework rather than maintaining in-house glue code — that's the core buy decision this assessment informs.
• Roadmap sequencing around a 2.0 migration. v1.22.2 introduces the first deprecation (Load_Method::ASYNC_DEFER) with an explicit removal target in Mantle 2.0. This is a planning signal: any feature work that touches asset loading should be scoped with the 2.0 migration in mind, and the team should start budgeting migration capacity now rather than at the 2.0 announcement.
• Asset pipeline behavior is a product surface, not an implementation detail. Under wp-asset-manager 2.0, a stylesheet using the defer load method now loads as async and raises a _doing_it_wrong() notice. That is a visible behavior change (and a debug-log/noise change) for existing sites. PM decision: treat "stylesheet load-method semantics" as a tracked user-facing behavior with QA coverage, not something left to a routine composer update.
• Dependency-upgrade policy. The constraint widening to ^1.4.0 || ^2.0 means projects that pull wp-asset-manager only transitively through this package will jump to 2.x on the next composer update — no explicit opt-in. This supports a decision to pin or stage dependency upgrades in CI, and to require a changelog review gate before merging lockfile bumps.
• Support-matrix scoping. Supporting both wp-asset-manager 1.x and 2.x simultaneously is a compatibility window, not a permanent state. Product should plan to publish a support statement (which wp-asset-manager majors are supported, and until when) so downstream consumers can make their own upgrade decisions.

When to Consider This Package

Consider adoption when:

• The team is building WordPress plugins or themes and wants Laravel ergonomics — Blade templating, a container, Eloquent-adjacent models, routing — without hand-rolling that layer.
• You already depend on (or are willing to depend on) alleyinteractive/wp-asset-manager; the asset contract in this release is only meaningful if that plugin is in the stack.
• You can tolerate a 1.x line with active deprecations ahead of a 2.0, and you have the release-management discipline to review transitive dependency bumps (composer update is not a no-op here).
• Your project is on a modern PHP runtime and is comfortable tracking an actively developed framework rather than a frozen, long-term-support dependency.
• You want a single maintained abstraction over WordPress asset registration rather than app-level code that reimplements enqueue/defer/async logic per project.

Look elsewhere when:

• The application is plain Laravel or plain WordPress — the integration value proposition doesn't apply, and you inherit dependency churn for no benefit.
• You need guaranteed API stability with no breaking changes on the horizon. The ASYNC_DEFER deprecation and the wp-asset-manager 2.x behavior change both point to a framework that is deliberately evolving toward a major release.
• You cannot absorb a silent behavior change on upgrade (e.g. regulated, accessibility-audited, or performance-budgeted front ends where defer → async materially alters render/execution order). Either pin wp-asset-manager to 1.x explicitly or postpone adoption.
• You require vendor-backed SLAs or a paid support contract; this is community/Alley-maintained OSS.

How to Pitch It (Stakeholders)

To executives: This is a maintenance release for our WordPress framework layer — no new features, no cost, no vendor change. The strategically relevant item is a deprecation (ASYNC_DEFER), which is the first concrete milestone on the path to the framework's 2.0. It gives us an early, low-cost signal to plan that migration rather than absorb it as unplanned work later. Risk introduced this cycle is small but real: a transitive dependency can now auto-upgrade to a new major on a routine composer update, and one asset-loading behavior changes as a result. We mitigate with a lockfile review gate and a targeted QA pass, not a project.

To engineering: v1.22.2 widens the wp-asset-manager requirement to ^1.4.0 || ^2.0, deprecates Mantle\Contracts\Assets\Load_Method::ASYNC_DEFER (removal in Mantle 2.0), and fixes a PHPStan catch.neverThrown false positive in HTML_Helpers::convertToHtmlEntities(). Two things to action: (1) projects consuming wp-asset-manager only transitively will land on 2.x on the next composer update — review the 2.0 changelog first, and note that stylesheets using defer now load as async and emit _doing_it_wrong(). (2) ASYNC_DEFER is passed through on 1.x and coerced to async on 2.x; the same coercion applies to scripts calling both async() and defer(). Grep for ASYNC_DEFER and for combined async()/defer() usage and migrate to an explicit single load method now, while the compatibility shim still exists.