HTML

Reader\Html\HtmlReader reads HTML into a UJO document: the HTML a block editor renders — that of phil/ujo, its ujo-* classes read back into the blocks they came from —, the HTML a paste brings from a word processor or another site, and the HTML of older texts. DefaultCompiler compiles HTML as written, for the purifier; the reader is what converts it into blocks, when a text is published as UJO or opened in a block editor. Formats puts each element beside the syntax of the other 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.`

The source is parsed by the HTML5 parser of PHP, Dom\HTMLDocument, as a browser parses it: tags left open are closed, misplaced ones moved, entities read. Any text is a document; the reader never throws. The constructor takes, in order, the phil/ujo normalizer the document is checked by, the EmbedServices a frame is matched against, the ExtractedElementStore inline drawings are stored by, and the SvgSanitizer that purifies them.

Blocks

The HTML of phil/ujo

The blocks phil/ujo renders carry the class of their type, which the reader reads back:

A stat block is read as its blocks, a class table as its table.

Inline

The white space of text is collapsed as a browser collapses it, out of <pre>.

Left out, and the losses

Scripts, styles, objects, forms and their fields and the head of a page are left out with their content. The title of a page, its language, <html lang>, and its <meta name="…" content="…"> are its metadata.

What the reader does not keep is listed in Reading::$losses, in the order of the source, up to 1 000: each Loss names the element, its path — body > div[2] > p[1], each element counted among its siblings of its name — and its LossReason:

A site shows them to the writer before publishing; phil/content-bundle does in phil:content:publish.

Inline drawings

An inline <svg> is extracted rather than written in the text: the reader writes it as SVG, purifies it with phil/svg-sanitizer — no script, no event handler, no reference outside the image, no foreignObject — and gives it to an ExtractedElementStore, which stores the file — a media library, a storage of the site — and returns its address. The drawing becomes an image of that address. Without a store, or when the store returns null or an address that is not http, https or relative, the drawing is left out and the loss recorded.

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);

Limits

Containers nest as deep as UJO allows, and those deeper are left out, their blocks kept. Elements nested more than 128 deep are read as their text, so that a document nested thousands deep is read in linear time without exhausting the stack.