jorisnoo / statamic-safe-entities
A Statamic addon that provides a Blade directive and Bard buttons for safe HTML entity insertion (soft hyphens, non-breaking spaces, etc.).
Package info
github.com/jorisnoo/statamic-safe-entities
Type:statamic-addon
pkg:composer/jorisnoo/statamic-safe-entities
Requires
- php: ^8.2
- statamic/cms: ^6.0
Requires (Dev)
- orchestra/testbench: ^10.0 || ^11.0
- phpunit/phpunit: ^11.0 || ^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A Statamic addon for safe HTML entity insertion in Bard, text, and textarea fields. Adds a Bard toolbar button for inserting soft hyphens, non-breaking spaces, en dashes, and other typography entities, plus Blade directives to render them safely.
Installation
Requires Statamic 6 and PHP 8.4 or later.
composer require jorisnoo/statamic-safe-entities
Configuration
Publish the config file to customize which entities are available:
php artisan vendor:publish --tag="safe-entities-config"
Default configuration:
return [ 'entities' => ['­', ' ', '–'], 'replacements' => [], ];
An indexed code uses the editor's translated label (or the code itself). To override it, use ' ' => 'Fixed space'. To insert a shorthand with a different rendered output, use '&nnbsp;' => ['output' => ' ', 'label' => 'Narrow space'].
replacements maps literal search strings to their output after escaping and entity restoration. For example, '<br>' => '<br>' converts a typed <br> in a plain text field to a line break. Replacement output is not escaped: use only trusted rules, and do not use markup-producing replacements with visitor input. Editors can see the configured patterns in Utilities → Special Characters.
Usage
Bard toolbar
Add the following button names to the field's existing Bard buttons list:
buttons: - bold - safeentities - entityvisibility
The & dropdown inserts a literal code at the cursor. The eye switches between codes and rendered characters without changing the stored content.
Blade directives
Two Blade directives are available for rendering entities safely:
@entities($text) — for text/textarea fields
Escapes the string for safe HTML output, then restores configured entity codes so they render as actual entities.
<p>@entities($entry->title)</p>
@entitiesHtml($html) — for Bard/rich-text fields
Restores double-encoded entities (&shy; back to ­) in trusted, already-rendered HTML. It does not sanitize HTML. For a Bard field without sets, the augmented value is an HTML string:
<div>@entitiesHtml($entry->content)</div>
A Bard field with sets yields a list of chunks instead. Pass only a text chunk's HTML to the directive; render each other set with its own template:
@foreach ($entry->content as $set) @if ($set->type === 'text') @entitiesHtml($set->text) @else @include('sets.'.$set->type, ['set' => $set]) @endif @endforeach
PHP
You can also call the methods directly:
use Noo\SafeEntities\SafeEntities; $text = SafeEntities::render($value); $html = SafeEntities::renderHtml($value);
Both methods accept an optional second argument to override which entities to restore:
SafeEntities::render($value, ['­', ' ']);
Testing
composer install
vendor/bin/phpunit
npm ci
npm test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Credits
License
The MIT License (MIT). Please see the license file for more information.
Maintainer releases
See RELEASING.md for versioning, changelog entries and the release command.