Statamic Safe Entities Laravel Package

Technical Evaluation

Architecture fit. jorisnoo/statamic-safe-entities is a Statamic addon (Statamic being a Laravel-based CMS), so it slots in as a Composer package consumed by an existing Laravel application rather than as standalone infrastructure. Its job is narrow and render-time: making sure entities in content are emitted safely. That is a shallow integration point — service provider registration, optionally a config file, optionally publishable assets — which keeps architectural coupling low and blast radius small. The removal of the auto-hyphenation feature in 0.2.2 actually improves architectural fit: the package now does one thing, and the dependencies that existed only to support hyphenation are gone, reducing the transitive surface it drags into our composer.lock.

Integration feasibility. High for a greenfield adoption, moderate for upgrades. Installing is a standard composer require plus a cache clear; there is no schema, no queue worker, no external service, and no runtime daemon. The friction is entirely in the 0.2.2 breaking change: any content that was relying on auto-hyphenation will render differently after the upgrade. Because no prior assessment or inventory data was supplied, we cannot yet quantify how much rendered output actually depends on that behavior — that is the single fact that gates the effort estimate.

Technical risk. Medium, concentrated in three places:

1. Silent output drift. Removing auto-hyphenation changes rendered markup without throwing an error. Long words in headings and body copy may now overflow or wrap differently. This is a visual regression class of bug that functional tests typically do not catch, and it is most likely to surface on narrow viewports and in fixed-width email or PDF templates.
2. Version-numbering signal. This is a breaking change shipped as a patch release (0.2.1 → 0.2.2). Semver permits that for 0.x versions, but it means automated dependency updaters (Dependabot, Renovate) can pull a behavior-changing release into a routine PR. We should pin and use an explicit update policy for 0.x addons.
3. Asset staleness. "Regenerate build assets" implies the distributed bundles changed. If any consuming project published those assets to public/ (or resources/), the published copy is now stale and must be re-published. A stale asset plus a new PHP class is an inconsistent-state failure mode that is easy to miss in review.

The removed dependencies are a genuine risk reduction (smaller supply chain, fewer upgrade blockers on future Statamic/Laravel major versions).

Key questions.

• Which Statamic and Laravel major versions does 0.2.2 declare support for, and does the removal of hyphenation dependencies change that support matrix?
• Is auto-hyphenation behavior that any of our templates, fieldtypes, or Antlers/Blade partials explicitly enabled or documented as expected output?
• Do we have snapshot or visual-regression coverage on rendered content that would catch overflow changes?
• Is the removal permanent (feature intentionally retired, maintainer recommends CSS hyphens instead) or a temporary revert that could return in 0.3.0?
• Was 0.2.2 tagged before or after the build-asset commit, i.e. do the shipped assets match the tagged source?
• Who owns this addon upstream — is it a single-maintainer project, and what is the release cadence and issue-response history?

Integration Approach

Stack fit. Native fit. It is a Composer package for a Laravel app running Statamic; no adapter layer, no bridge service, no protocol translation. Installation is a lockfile change and a service-provider registration handled by Laravel's package discovery. Nothing else in the stack needs to know it exists.

Migration path. Two distinct paths depending on our starting state:

• Adopting fresh (no existing install, or install at ≥ 0.2.2): straightforward — require the constraint, publish config/assets if the readme calls for it, run php artisan view:clear and config:clear, and verify rendered output on a representative page set. No migration of content required, because we are not adopting the hyphenation behavior in the first place.
• Upgrading from ≤ 0.2.1: treat as a behavior migration, not a dependency bump. Sequence: (1) inventory where hyphenation is visible — grep templates for the modifier, compare rendered HTML of the top N high-traffic pages before and after in a staging environment; (2) decide the replacement for any lost behavior (CSS hyphens: auto / ­ / word-break are the usual substitutes, and CSS is the better long-term answer since it is presentation, not content); (3) update, re-publish any vendor assets, clear caches; (4) re-run the same rendered-HTML comparison and diff.

Regardless of path, do not let a bot merge the 0.2.1 → 0.2.2 bump. Require a human review gate on 0.x addon updates.

Compatibility. Verify the package's composer.json constraints against our pinned Statamic and PHP versions before committing. The dependency removal can only widen compatibility, never narrow it, which is favourable — but confirm the release did not also bump the minimum PHP or Statamic version in a way that conflicts with our current LTS choice. If we run multiple sites on differing Statamic majors, confirm 0.2.2 resolves cleanly on the oldest one first, since that is where a failure is cheapest to discover.

Sequencing. Lowest-risk order: pin 0.2.2 in a single non-production environment → rendered-output comparison → deploy to one lower-traffic production site if the estate is multi-site → then roll forward everywhere. If adoption is fresh rather than an upgrade, collapse this to a single staging verification pass. Publish the constraint as an explicit version rather than a floating ^0.2 for the first cycle.

Operational Impact

Maintenance. Ongoing cost is near zero — no configuration to drift, no data to backfill, no cron. The real maintenance decision is ownership of the removed feature: if any part of the content team depended on auto-hyphenation, that responsibility now transfers to us, most cleanly as a CSS rule in the theme rather than a re-vendored fork. Budget a small amount of front-end time for that if the inventory step shows real usage. Also budget for the process fix: an explicit 0.x upgrade policy so patch-level breaking changes get eyes.

Support. The addon is small and single-maintainer, so upstream support should be assumed to be best-effort. Our internal support surface is the content team noticing typography changes — which is exactly the kind of ticket that arrives without a linked cause. Pre-empt it by briefing the content/design stakeholders on the 0.2.2 behavior change before rollout, so a wrap-change report is recognized as expected rather than investigated as a new bug. No end-user-facing support burden is expected.

Scaling. Effectively free. The package operates at render time with no per-request state, no I/O, and no external calls. It scales linearly with page renders like any other template-level function and will never be the bottleneck. Removing dependencies marginally improves deploy time and image-build cache stability. Full-page or CDN caching makes the cost negligible at any realistic traffic level.

Failure modes.

• Typography/layout regression (most likely): long unbreakable strings overflow containers post-upgrade. Detected by visual diff; mitigated by the CSS substitute above.
• Stale published assets: PHP updated but shipped bundles not re-published, producing inconsistent front-end behavior. Mitigated by making asset re-publish an explicit, checklist step.
• Silent version drift via bots: an automated PR merges a behavior change with no rendered-output review. Mitigated by pinning and requiring human approval on 0.x.
• Upstream abandonment: single-maintainer project, feature removed at 0.2.x. Low severity given the package's small size — the fallback is to inline the sanitization logic into our own codebase, which is a day of work, not a project.
• Feature reinstatement: if hyphenation returns in 0.3.0, we would face a second behavior change in the opposite direction. Track the upstream issue thread so we are not surprised.

Ramp-up. Minimal. Any Laravel developer can read the whole package in under an hour. The ramp-up that matters is organizational, not technical: establishing the 0.x dependency policy and the rendered-output verification step, and making sure the content and design stakeholders know why typography may shift. Plan a half-day for inventory and verification on the upgrade path, and roughly an hour for a fresh install.