Search by

jorisnoo / statamic-safe-entities

jorgenoo

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

Statistics

Installs: 615

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

0.3.0 2026-11-19 05:26 UTC

This package is auto-updated.

Last update: 2026-11-19 06:59:37 UTC


README

Latest Version on Packagist Tests Total Downloads

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, '&lt;br&gt;' => '<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 (&amp;shy; back to &shy;) 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, ['&shy;', '&nbsp;']);

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.