README

UJO (Universal JSON Output) documents in a Symfony application: a field that checks them, a constraint, and safe HTML in Twig.

phil/ujo-bundle integrates phil/ujo into Symfony. It declares the library's parts as services built from a short configuration — whether raw HTML blocks are accepted, how large a document may be, how deep blocks may nest —, adds the ujo_html and ujo_text filters and functions to Twig, a UjoType form field that receives the JSON a block editor writes and keeps it in canonical form, and a ValidUjo constraint that checks a document and, if asked, the types of its blocks. It does not ship the block editor itself, nor store documents.

It is for any Symfony application whose writers compose in a block editor that writes UJO: the field and the constraint stop an invalid or unwanted document at the form, and the filters render stored documents purified, under today's rules.

It is a Symfony bundle on phil/ujo, symfony/form and symfony/validator. Twig is optional: the filters and functions are registered when it is installed. Every service is the library's own class, declared under its class name, so an application replaces any of them by redefining it.

Status

Part	State
Configuration: `allow_raw`, `max_bytes`, `max_depth`, `max_blocks`, `max_html_length`, `max_raw_length`	Implemented and tested
Services: `BlockTypeRegistry`, `Normalizer`, `HtmlRenderer`, `PlainText`, `JsonDecoder`, `Ujo`	Implemented and tested
`ujo_html` and `ujo_text`, filters and functions	Implemented and tested
`UjoType` and `UjoTransformer`	Implemented and tested
`ValidUjo`, with accepted types and a validation level, shape or publication; messages in English and French	Implemented and tested

Documentation

Document	What it covers
Installation	Requirements, installing and enabling the bundle.
Configuration	Every option, the services, and replacing one.
Twig	`ujo_html` and `ujo_text`.
Forms and validation	`UjoType`, its options, and the `ValidUjo` constraint.
Extension points	What an application implements, configures, replaces or relies on.
Testing	The bundle's tests, and how to test a form that holds a document.
Reference	Every class of the bundle, with its role.

Quick start

composer require phil/ujo-bundle

use Phil\UjoBundle\Infrastructure\Form\UjoType;
use Phil\UjoBundle\Infrastructure\Validator\ValidUjo;

$builder->add('body', UjoType::class);            // canonical JSON in, canonical JSON out

#[ValidUjo(types: ['paragraph', 'header', 'list', 'quote', 'image'])]
public ?string $body = null;

{{ article.body|ujo_html }}
<meta name="description" content="{{ article.body|ujo_text|u.truncate(160) }}">

Requirements

PHP 8.5 or later, Symfony 8.2 and phil/ujo. Twig 3.21, for the filters and functions.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

phil / ujo-bundle

Package info

Security

Statistics