Mantle Framework Laravel Package

Technical Evaluation

Architecture fit

Mantle is Alley's Laravel-components-for-WordPress framework, and this release is confined to its asset pipeline layer — the wp-asset-manager integration that backs Mantle's script/style registration API. The architectural fit is therefore unchanged: this is a dependency-alignment patch on the maintained 1.x line, not a re-architecture. The notable shift is that Mantle now acts as a conduit for a downstream major version (wp-asset-manager 2.0), which means Mantle's own stability guarantees are partially coupled to a package it does not control.

Integration feasibility

Effort is low at the Composer level and moderate at the verification level. The constraint widening to ^1.4.0 || ^2.0 means any project that pulls wp-asset-manager only transitively through Mantle will silently land on 2.x at the next composer update. Feasibility hinges on one audit task: enumerate every asset registration using defer, async-defer, or a script that calls both async() and defer(), and confirm the resulting load semantics are acceptable.

Technical risk — rated Medium

• Silent transitive major upgrade. The highest-risk item. No change to the consuming application's composer.json is required to receive a new major of a third-party plugin. Standard lockfile discipline protects existing builds, but composer update in CI or on a maintenance branch is enough to cross the boundary.
• Behavioral change, not just a version bump. A stylesheet declared with defer loads as async on 2.x. On front-end this can manifest as render-order or cascade differences that are hard to attribute back to a Composer update.
• _doing_it_wrong() notices. These are developer-facing correctness signals. In WordPress test harnesses that promote notices to failures, they can break CI independent of any user-visible change.
• Deprecation of Load_Method::ASYNC_DEFER. Not a break in 1.x — Mantle passes the constant through on wp-asset-manager 1.x and coerces to async on 2.x — but it is a hard removal scheduled for Mantle 2.0. Any code referencing the constant (including the async() + defer() combination path) is now on a clock.
• Two-major support matrix. Mantle 1.22.x must behave correctly against wp-asset-manager 1.4.x and 2.x. That doubles the asset-layer test surface for the maintainers, and consumers on 1.x are effectively testing a configuration the maintainers will increasingly treat as legacy.

Key questions

1. What is the published timeline for Mantle 2.0, and what is the support window for the 1.x line after it ships?
2. Do the _doing_it_wrong() notices fire only with WP_DEBUG enabled, or unconditionally? This determines whether they are a production concern or a development-only signal.
3. Does Mantle emit its own deprecation notice when ASYNC_DEFER is used, or is the signal only the downstream _doing_it_wrong()?
4. Which Mantle APIs route through wp-asset-manager versus WordPress core's wp_enqueue_* — i.e. what is the actual blast radius of the 1.x/2.x split?
5. Are there other first-party Alley packages that constrain wp-asset-manager independently, and could those constraints conflict with Mantle's new range?
6. Does wp-asset-manager 2.0 carry its own minimum PHP/WordPress requirements that are stricter than Mantle 1.x's?

Integration Approach

Stack fit

Unchanged for the standard Mantle profile: WordPress + Composer + a Laravel-style application structure. The new consideration is that wp-asset-manager must now be reasoned about as a first-class member of the dependency graph rather than an implementation detail. Teams using Bedrock or a comparable Composer-driven WordPress layout already have the tooling to express that constraint explicitly.

Migration path

Two viable paths, and the choice should be made deliberately rather than by default:

• Defer (recommended for most teams initially). Add an explicit "alleyinteractive/wp-asset-manager": "^1.4" constraint to the root composer.json while on Mantle 1.22.x. This converts an implicit transitive decision into an explicit, auditable one and buys time to complete the load-method audit. It does not block the Mantle upgrade.
• Adopt. Remove the deferral and take 2.x, paired with the asset audit and a front-end regression pass. Appropriate where the asset surface is small, well-tested, or already avoids defer/async-defer.

Either way, the migration is reversible at the Composer level; the risk is front-end regression, not data or schema.

Compatibility

• Mantle 1.22.x is designed to span wp-asset-manager 1.4.x and 2.x, so both configurations are nominally supported — the divergence is in load semantics, not API surface.
• ASYNC_DEFER remains functional on 1.x and is coerced on 2.x, so application code compiles in both configurations; only behavior differs.
• The PHPStan fix in HTML_Helpers::convertToHtmlEntities() is a static-analysis correctness change and carries no runtime compatibility implication, though teams running PHPStan at a pinned baseline may see their baseline entry become stale.

Sequencing

1. Inventory asset registrations — flag every use of defer, async-defer, and any script calling both async() and defer().
2. Add an explicit wp-asset-manager constraint at the root so the version is a decision, not an accident.
3. Upgrade Mantle to 1.22.2 and run the full test suite with WP_DEBUG enabled to surface _doing_it_wrong() output.
4. Canary the front-end on a staging environment with the 2.x constraint active; compare asset loading and rendering.
5. Only then promote 2.x to production, and separately schedule removal of ASYNC_DEFER call sites ahead of Mantle 2.0.

Operational Impact

Maintenance

Ongoing maintenance load is low but concentrated: the work is a one-time asset audit plus a standing obligation to eliminate ASYNC_DEFER usage before Mantle 2.0. Teams that skip the audit inherit an open-ended debugging cost, because defer/async regressions present as visual or performance symptoms rather than errors. Owning an explicit wp-asset-manager constraint is the single highest-leverage maintenance action and costs one line.

Support

Support surface is essentially unchanged — no new APIs to learn, no new configuration. The support burden shifts toward diagnosis: "why did our stylesheet load order change after a routine dependency update" is now a supported question, and the answer requires someone who understands both Mantle's asset abstraction and wp-asset-manager's load methods. Worth documenting internally as a known-issue playbook.

Scaling

No scaling implications — this is a client-side asset loading concern, not a runtime or throughput one. The one adjacent consideration: async versus defer has measurably different effects on Core Web Vitals and paint timing, so on high-traffic properties the behavior change should be validated against real-user performance data rather than assumed neutral.

Failure modes

• Silent major upgrade on composer update — the dominant failure mode; manifests as a front-end change with no obvious code-level cause.
• Stylesheet render-order shift — defer → async changes cascade/ordering guarantees; can produce flashes of unstyled content or override regressions.
• CI breakage from _doing_it_wrong() — test harnesses that promote notices to failures will go red on upgrade, arguably the good outcome since it surfaces the issue early.
• Deprecation surface in production — if notices are not gated behind WP_DEBUG, expect log noise and potential customer-visible output in misconfigured environments.
• Mixed-version fleet — sites pinned to 1.x and sites on 2.x behaving differently from identical Mantle code, which complicates shared plugin/theme distribution.

Ramp-up

Low. A developer familiar with WordPress enqueueing and Composer needs well under a day to understand the change; the substantive effort is the asset inventory, which scales with the size of the theme/plugin asset surface. The ASYNC_DEFER deprecation is trivially understood but easy to forget — assign it an owner and a ticket against the Mantle 2.0 milestone rather than leaving it as tribal knowledge.