HTML

Reader\Html\HtmlReader lit du HTML et en fait un document UJO : le HTML que produit un éditeur par blocs (celui de phil/ujo, dont les classes ujo-* sont relues en les blocs d'où elles viennent), le HTML qu'apporte un collage depuis un traitement de texte ou un autre site, et le HTML de textes plus anciens. DefaultCompiler compile le HTML tel qu'il est écrit, pour l'assainisseur ; c'est le lecteur qui le convertit en blocs, quand un texte est publié en UJO ou ouvert dans un éditeur par blocs. Formats place chaque élément à côté de la syntaxe des autres formats.

$reading = new HtmlReader()->read('<h2>Rules</h2><p>Roll <strong>two</strong> dice.</p>');

$reading->document->blocks[0];   // a `header` block, level 2, its anchor `rules`
$reading->document->blocks[1];   // a `paragraph` block, `Roll <b>two</b> dice.`

La source est analysée par l'analyseur HTML5 de PHP, Dom\HTMLDocument, comme un navigateur l'analyse : les balises laissées ouvertes sont fermées, celles qui sont mal placées sont déplacées, les entités sont lues. Tout texte est un document ; le lecteur ne lance jamais d'exception. Le constructeur prend, dans l'ordre, le normaliseur de phil/ujo qui vérifie le document, les EmbedServices auxquels un cadre est comparé, l'ExtractedElementStore qui stocke les dessins en ligne, et le SvgSanitizer qui les assainit.

Blocs

Le HTML de phil/ujo

Les blocs que produit phil/ujo portent la classe de leur type, que le lecteur relit :

Un bloc de statistiques se lit comme ses blocs, une table de classe comme son tableau.

En ligne

Les espaces du texte sont réduites comme un navigateur les réduit, hors de <pre>.

Ce qui est laissé de côté, et les pertes

Les scripts, les styles, les objets, les formulaires et leurs champs et l'en-tête d'une page sont laissés de côté avec leur contenu. Le titre d'une page, sa langue, <html lang>, et ses <meta name="…" content="…"> sont ses métadonnées.

Ce que le lecteur ne garde pas est listé dans Reading::$losses, dans l'ordre de la source, jusqu'à 1 000 : chaque Loss nomme l'élément, son chemin (body > div[2] > p[1], chaque élément compté parmi ses frères du même nom) et sa LossReason :

Un site les montre à l'auteur avant la publication ; phil/content-bundle le fait dans phil:content:publish.

Dessins en ligne

Un <svg> en ligne est extrait plutôt qu'écrit dans le texte : le lecteur l'écrit en SVG, l'assainit avec phil/svg-sanitizer (aucun script, aucun gestionnaire d'événements, aucune référence hors de l'image, aucun foreignObject) et le donne à un ExtractedElementStore, qui stocke le fichier (une médiathèque, un stockage du site) et retourne son adresse. Le dessin devient une image de cette adresse. Sans magasin, ou quand le magasin retourne null ou une adresse qui n'est ni http, ni https, ni relative, le dessin est laissé de côté et la perte est enregistrée.

final class MediaStore implements ExtractedElementStore
{
    public function store(string $content, string $mediaType, string $name): ?string
    {
        return $this->library->upload($content, $mediaType, $name)?->url();
    }
}

$reading = new HtmlReader(store: new MediaStore($library))->read($html);

Limites

Les conteneurs s'imbriquent aussi profondément que le permet UJO, et ceux qui sont plus profonds sont laissés de côté, leurs blocs gardés. Les éléments imbriqués sur plus de 128 niveaux sont lus comme leur texte, pour qu'un document imbriqué sur des milliers de niveaux se lise en temps linéaire sans épuiser la pile.