Statamic Safe Entities Laravel Package

Getting Started

• Install with composer require jorisnoo/statamic-safe-entities. The addon is auto-discovered by Statamic; there is typically no service provider to register by hand. Check whether a config file is shipped — if so, publish it and commit it so entity/typographic behaviour is consistent across environments.
• Look first at src/Modifiers/ to confirm the exact modifier handle (this is a Statamic modifier addon, so the public API is the modifier name, not a facade), then the README for the documented signature and any config keys. Skim CHANGELOG.md before installing: 0.2.2 removed the auto-hyphenation feature and its dependencies, so any snippet you copy from an older blog post that mentions soft hyphens no longer applies.
• First use case: rendering CP-authored headlines and body copy in Antlers so punctuation (&, <, curly quotes, em dashes) is output as entities without corrupting already-encoded content.

  <h2>{{ headline | safe_entities }}</h2>
  

• Verify the modifier's escaping contract immediately: render a value containing & and confirm whether you need | raw downstream or whether the modifier is designed to be used inside an escaped context. This is the single decision that determines how you wire it everywhere else.
• Pin the version. 0.2.2 is a breaking change in a 0.x line — use "jorisnoo/statamic-safe-entities": "0.2.2" (or ^0.2.2) rather than * so a future 0.x removal doesn't surprise a deploy.

Implementation Patterns

• Wrap it in a shared partial. Rather than sprinkling the modifier across templates, create one Antlers partial (e.g. partials/text) that owns escaping/entity handling and takes a text parameter. Every heading, caption, and rich-text excerpt renders through it. When the addon's behaviour changes again, you edit one file.
• Mind the chain order. Apply safe_entities after transformations that introduce characters and before anything that re-parses HTML.

  {{ content | markdown | safe_entities }}
  

  If you need widont/smartypants-style typographic passes, run them before safe_entities so the entities it produces are the final form. Do not run it after a modifier that expects raw &/<.
• Blade and controllers. Statamic's modifier chain is available in Blade via Statamic::modify($text)->safeEntities(), which keeps behaviour identical between Antlers and Blade views — useful when a Livewire component renders the same field as an Antlers template.
• Bard and Replicator. For inline text inside Bard sets, apply the modifier to the leaf text nodes rather than to the whole rendered HTML blob; running it over full set markup risks touching attribute values. If the addon exposes a tag pair, prefer that for set-level rendering.
• Store raw, encode at render. Keep the original characters in the Markdown/field data and apply safe_entities only at output. This keeps the Statamic search index, the CP preview, and any API/JSON consumers clean.
• Cache the expensive contexts. The modifier itself is cheap, but if you render it across a large listing (e.g. 200 search results), wrap the loop in Statamic's {{ cache }} tag so the entity pass and surrounding markup are computed once.
• Regression test the upgrade. Add an assertion that rendered output contains no ­:

  $this->get('/')->assertDontSee('­', false);
  

  and a snapshot/assertSee test for a known string with curly quotes and an ampersand. This is the fastest way to catch both the hyphenation removal and any accidental double-encoding.

Gotchas and Tips

• Double-encoding is the classic failure. Statamic escapes {{ }} output by default; if the modifier already returns &, you can end up with & on screen. Establish early whether the modifier returns a "safe" string (so no | raw is needed) or expects | raw. Test with a value containing &, <, and an existing &.
• The 0.2.2 breaking change is a visual regression, not a fatal error. Nothing will throw — long words in narrow columns and justified text simply stop breaking. Fix it in CSS rather than PHP: set lang on <html>, then hyphens: auto; overflow-wrap: break-word; on the affected selectors. Budget design QA time for headline/card layouts after upgrading.
• Don't feed entity-encoded text into JSON-LD, meta descriptions, or OpenGraph tags. Structured data needs json_encode-style escaping, not HTML entities; run the modifier only on the HTML rendering path. Same for alt attributes and title attributes where & will be re-decoded inconsistently by different crawlers.
• Clean up after the dependency removal. If you had published a hyphenation dictionary/config in an earlier install, delete the stale file and run php artisan config:clear && php artisan view:clear (and php please stache:clear if you changed field-level rendering). Leftover config keys after a removal are silent no-ops that make debugging confusing.
• Multibyte correctness. Test with curly quotes, em/en dashes, ellipses, non-breaking spaces, and a non-Latin string. Entity conversion on UTF-8 input is where mb_* vs byte functions diverge; a passing ASCII test proves nothing.
• Extension points. The modifier is a normal class, so for a bespoke entity map (e.g. house-style replacements, ™, ®) it is often cleaner to copy the modifier into app/Modifiers/ and register your own handle than to patch vendor code. If the addon allows config-driven replacement maps, prefer that and keep the override in config/statamic/safe-entities.php.
• Debugging output. Use {{ dump }} or php please tinker to compare raw field value vs. modifier output when something renders literally as &. If output looks stale, Statamic's view/stache caches are the usual culprits, not the modifier.
• Watch the 0.x churn. Two removals in one release line suggests the API is still settling; keep the addon behind an explicit version constraint and re-read the changelog on every bump rather than relying on composer update to be safe.