Statamic Heroicons Laravel Package

Technical Evaluation

Architecture fit This is a presentation-layer package (Heroicon rendering for Laravel Blade plus a Statamic tag surface). It sits at the edge of the stack: no persistence, no queue, no external service dependency, no migration surface. Architectural risk is inherently low, and adoption does not constrain application domain design. The release confirms that positioning — all four changes are either platform support expansion or rendering hardening, with no new infrastructure footprint.

Integration feasibility Low-effort for existing consumers. v3.3 is a minor bump: additive Statamic 6 support, plus three behavioural corrections. Integration work is bounded to (a) confirming the host app's Statamic major version, (b) verifying the CI-validated matrix overlaps our runtime, and (c) visual regression on any view that renders icons with dynamic or optional variant/icon input. No data migration, no config schema change, no API contract change signalled.

Technical risk

• Statamic 6 as a hard dependency boundary: supporting Statamic 6 typically means the package's composer constraint expands. If our constraint is written loosely (^3.0), a composer update can silently move us onto the Statamic 6 path. Pin deliberately.
• Behavioural diffs that are not "breaking" by semver but are visible: "preserve case-insensitive icon parameters and camel-case wildcard names" and "harden tag rendering when variant/icon input is missing" both change rendered output for inputs that previously produced different results. The hardening in particular converts a previously broken/erroring render into a graceful one — desirable, but it can mask a genuine template bug that was previously loud.
• SVG attribute escaping is a correctness and injection-surface improvement; low risk, but it can alter byte-level output for any attribute containing ". Snapshot tests on rendered markup will flag this.
• CI coverage claim of PHP 8.5 is forward-looking. Treat as intent, not as a validated production target for us until our own runtime is on 8.5.

Key questions

1. Does the composer constraint on Statamic widen in a way that permits Statamic 6 on an app still on Statamic 5, or is it correctly disjunctive (^5.0|^6.0)?
2. What is the documented minimum Laravel/PHP for the Statamic 6 path specifically — is it the same as the Statamic 5 path, or does it raise the floor?
3. For the missing-variant/icon hardening: does it render nothing, render a fallback, or log? That determines whether it hides template defects.
4. Is the case-insensitivity / camel-case wildcard preservation a restoration of prior behaviour (regression fix) or a new guarantee we can now depend on?
5. Are there any deprecations queued behind the Statamic 6 work (e.g. dropping Statamic 5) with a stated horizon?

Integration Approach

Stack fit Direct fit for a Laravel + Blade front end, and now an explicit fit for a Statamic 6 CMS-backed site. The package is a leaf dependency — it asks nothing of our architecture and imposes no runtime service. The only meaningful stack question is which CMS major we are on, since that is what v3.3 changes.

Migration path Incremental and reversible. Recommended path: pin the current version, run the upgrade in a branch, execute the render-path regression suite, then promote. Because this is a rendering package, rollback is a composer pin revert with no state to unwind — the cheapest possible reversal. If we are not on Statamic 6, this release is effectively a patch-grade change delivered as a minor; we can adopt it purely for the hardening and escaping fixes.

Compatibility Two axes to validate rather than assume: CMS major (Statamic 5 vs 6) and PHP runtime (the CI matrix covers 8.2–8.5; our actual runtime must be inside that window). Laravel 12 is the tested pairing for the Statamic 6 path — confirm our Laravel minor is inside the supported range even if we are on Statamic 5. Front-end compatibility is the third axis: confirm the icon set version and any Tailwind/sprite assumptions are unchanged, since the release notes do not mention icon-set changes.

Sequencing

1. Inventory all icon render sites, separating static (literal icon names) from dynamic (variable variant/icon, wildcard names) — dynamic sites carry the behavioural-diff risk.
2. Adopt the patch-level fixes (escaping, missing-input hardening, case preservation) first on the current CMS major; this isolates rendering changes from the CMS upgrade.
3. Upgrade Statamic major separately, with the package bump travelling alongside it rather than ahead of it.
4. Only then widen PHP to 8.5 if that is on our roadmap, treating it as an independent step.

Operational Impact

Maintenance Near-zero steady state. No scheduled jobs, no migrations, no config drift. The ongoing cost is version-tracking against Statamic majors, which is the package's real maintenance axis — expect this dependency to force a decision each time Statamic ships a major, not on a routine cadence.

Support Well-covered by the upstream CI matrix (Statamic 6 × Laravel 12 × PHP 8.2–8.5), which is a stronger signal than most packages of this size provide. The absence of any deprecation notice in v3.3 means no forced support deadline. The main support gap is documentation of the new fallback behaviour for missing icon/variant input — that is a question our own team will field from template authors.

Scaling Non-issue. Rendering work is per-request and proportional to icon count in the view, unchanged by this release. The escaping change adds negligible per-attribute cost. No caching, I/O, or memory implications.

Failure modes

• Silent degradation: the missing-input hardening means a malformed tag now renders gracefully instead of failing loudly. A typo'd icon name could ship to production unnoticed. Mitigate with a build- or CI-time check that fails on unknown icon references, or by asserting on rendered output in tests.
• Markup drift: attribute escaping changes byte output where " appears in values. Any snapshot or string-equality test on rendered SVG will break — this is expected, not a defect.
• Version skew: a loose composer constraint pulling Statamic 6 transitively on an app authored against Statamic 5. Pin explicitly.
• Case-sensitivity assumptions: if any downstream code parses rendered class names or icon identifiers, the preserved casing/camel-case behaviour needs confirming against that parser.

Ramp-up Minutes for a developer already fluent in Blade and Statamic Antlers. The only learning is the new fallback semantics for missing inputs — worth a short note in the team's component docs so template authors know that a missing variant no longer surfaces as a visible error. No specialised knowledge required, no dedicated owner needed beyond whoever owns front-end dependencies.