Rich text
When content arrives as HTML saved from a rich text editor, or as plain text typed into a form, Markup converts it into components. It handles a practical subset of HTML, reports anything it couldn't convert, and needs no browser.
<x-doc::markup :html="$slide->body" />
<x-doc::markup :text="$prompt" />
<x-doc::markup :html="$slide->body" styles="original" blank-paragraphs="keep" />use Quoin\{Column, Document, Page};
use Quoin\Markup\{Markup, MarkupOptions, StyleMode};
use function Quoin\pt;
$slide = '<h2>Agenda</h2><p>Welcome to <b>Quoin</b>.</p><ol start="3"><li>Intro</li><li>Demo</li></ol>';
$document = Document::make(Page::letter()->body(
Column::make(
Markup::html($slide, new MarkupOptions(styles: StyleMode::Theme)),
Markup::text("Line one\nLine two\n\nA new paragraph."),
)->gap(pt(8)),
));The knowledge base article example converts a whole help article this way.
In Blade, bind the value with :html rather than html, otherwise Blade escapes the HTML before it is converted.
Markup::text() turns each newline into a line break and each blank line into a new paragraph. Characters like < are treated as plain text.
Writing HTML in the template
For a simple table, or a heading and a few paragraphs, you can write plain HTML between the tags. It's converted the same way as :html, and takes the same styles, blank-paragraphs, images and toc attributes:
<x-doc::card title="Summary">
<x-doc::markup>
<h3>Results</h3>
<p>Totals for {{ $period }}.</p>
<table>
<tr><th>Item</th><th>Amount</th></tr>
@foreach ($lines as $line)
<tr><td>{{ $line->name }}</td><td>{{ $line->amount }}</td></tr>
@endforeach
</table>
</x-doc::markup>
</x-doc::card>Blade runs first, so loops, conditions and {{ }} echoes work as usual, and an echoed value stays text: {{ '<b>' }} shows <b>, it doesn't make anything bold. Your own Blade components can go inside too, as long as they render HTML. Tags from this package can't, because they aren't HTML; put them next to the markup tag instead. The tag takes exactly one of: HTML in its slot, :html or :text.
Headings and the table of contents
Headings in converted HTML are ordinary headings, so a table of contents lists them. When the HTML comes from authors and the table of contents should list only your own headings, turn that off for the whole tag:
<x-doc::toc />
<x-doc::h1>Unit 1</x-doc::h1>
<x-doc::markup :html="$unit->intro" toc="false" />use Quoin\{Document, Page, Text, Toc};
use Quoin\Markup\{Markup, MarkupOptions};
$intro = '<h2>Warm-up</h2><p>Read the passage.</p>';
$document = Document::make(Page::a4()->body(
Toc::make(),
Text::h1('Unit 1'),
Markup::html($intro, new MarkupOptions(toc: false)),
));Every h1 to h6 the tag converts is left out, wherever it sits: in a list, a table or a quote. They still look like headings and keep their PDF bookmarks, the same as toc="false" on a single heading. quoin.markup.toc sets the default for every markup tag, and toc="true" turns it back on for one. In Word, the headings come back if someone updates the table of contents field (see Word export).
Putting ->toc(false) on the converted result doesn't do this: like any style on a box, it applies to the box itself, not to the headings inside it. Use the option.
Inside a line of text
Put markup inside a text tag and it joins that line, picking up the surrounding style:
<x-doc::text bold>× <x-doc::markup :html="$label" /></x-doc::text>In PHP, Markup::flatten() does the same, merging the converted content into a single Text. Block-level content is flattened and images are dropped; both are reported.
What gets converted
| HTML | Becomes |
|---|---|
p, div | a paragraph |
h1 to h6 | the theme's headings (h5 and h6 use the h4 style) |
b, strong, i, em, u, s, strike, del, span, br | inline formatting |
a href | a link, for http, https, mailto, tel and #fragment URLs |
ol, ul, li | a list, including start and type on ol and value on li |
img | an image, loaded by your resolver (see below) |
figure, figcaption | the content with its caption underneath |
iframe, video, audio | a paragraph linking to the source; one whose src is missing, not a supported link or contains a control character is left out, with a note |
blockquote | a quotation, styled by the theme's blockquote decorator. A trailing cite or footer becomes its attribution |
mark | inline text with a highlight |
pre | a block in the pre style: monospace, with spaces, tabs and line breaks kept. <pre><code> gives one block. With class="language-x" (or lang-x, on the code or the pre) it becomes a code block with syntax highlighting; turn that off with MarkupOptions(code: false) |
code, kbd, samp, tt | inline monospace text in the code style |
table, caption, thead, tbody, tfoot, tr, td, th | a table: header rows repeat on every page, colspan and rowspan are kept, and columns are sized by their content. In original mode a width on a cell sets its column and a width on the table sets the table; a table width is kept as written but never wider than its container, and columns wider than the space they have are scaled down to fit (percentages over 100% are scaled to 100%, with a note). Nested tables are flattened into paragraphs, with a note |
hr | a horizontal rule; in original mode border-color or color sets its color |
other block tags, like section | the tag is dropped, and its content kept as paragraphs |
| anything else | the tag is dropped, and its content kept inline |
script, style, template, head, noscript, object and embed are removed along with everything inside them. Tables and rules take the named styles markup.table, markup.th, markup.td and markup.hr, which you can restyle through quoin.styles. Classes, ids and data-* attributes are ignored. Empty paragraphs are dropped unless you ask to keep them.
Style modes
theme(the default): the HTML provides the structure, and your theme decides how it looks. Inlinestyle="…"attributes are ignored.original: inline styles are applied on top of the theme. Color, font size, weight, italic and text decoration work everywhere.background-colorworks on spans too. Alignment, margin, padding and sizes work on block elements only. Column properties on adivmake a column flow. Anything else is dropped and reported.
Pasted CSS is never rejected, but it is limited to what a page can hold. A font-size is clamped to 1 to 400pt and every other length to plus or minus 2000pt, and each clamp is reported as an approximation. A value that isn't a finite number is dropped. A height smaller than its content acts as a min-height, so nothing is cut off, and a max-height is not applied; both are reported. Negative margins are kept.
Columns
In original style mode, a div (or a block tag that would otherwise be dropped, like section) whose style attribute sets column-count or columns (a count) becomes a column flow. Only the style attribute is read, never a stylesheet.
<div style="column-count: 2; column-gap: 24pt; column-rule: 1pt solid #999">
<p>…</p>
</div>column-countsets the number of columns.columnssets it too: only its count is read, and a width in it is ignored. A count that would make the columns narrower than 72pt on the page is reduced until they are at least that wide, with one note. PDF, HTML and Word all use the reduced count.column-gapsets the gap andcolumn-rulethe width and color of the rule, but only beside a count: withoutcolumn-countorcolumns, they're dropped with a note and the content stays in one column.column-span,column-widthandcolumn-fillare dropped, with a note. The flow has no way to span columns, work out a count from a width, or leave columns unbalanced.- On
p, headings, lists and tables the column properties are dropped, with a note. - Box styles on the same
div, such as a border, background or padding, go on a box around the flow.
In theme mode, the default, author styles are ignored, so the content stays in one column. A flow made this way never throws for where it ends up. Inside a table cell, a row or another flow it lays out as one column, with a note.
Images
The conversion never downloads an <img src> itself. You give it a resolver: a function that receives the trimmed src and returns the image data, or null if the image can't be found.
use Quoin\{Document, Page};
use Quoin\Markup\{Markup, MarkupOptions};
$png = base64_decode('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==');
$markup = new MarkupOptions(images: fn (string $src): ?string => $src === 'logo.png' ? $png : null);
$document = Document::make(Page::letter()->body(
Markup::html('<p><img src="logo.png" width="40"></p><p><img src="gone.png" alt="Missing logo"></p>', $markup),
));The resolver is called once per distinct src in a conversion and its answer is reused, null included. When an image is missing, its alt text is shown in italics. Bytes that aren't a readable image, such as a cut-off download, are treated the same as null: the alt text, or a dropped note when there is none, and the rest of the document is made. In Laravel, set quoin.markup.images to a resolver class. The Laravel configuration page has a full example.
Treat src as user input
Your resolver decides which files can be read. Don't pass src straight to the filesystem or a storage disk. Check it against the paths you expect, and reject anything containing ...
Conversion warnings
Markup records everything it couldn't convert exactly and passes the notes to each export's warning callback and fidelity report. There are two kinds:
- Approximated: the content is there but looks different. For example, an iframe shown as a link, a missing image shown as its alt text, an unknown tag removed with its content kept, or invalid UTF-8 replaced with U+FFFD.
- Dropped: the content is gone. For example, a missing image with no alt text, a link with an unsupported URL, or an unsupported CSS property.
onWarning gets the message. If the callback takes a second parameter, it also gets a FidelityReport with level (FidelityLevel::Approximated or Dropped), format, feature and path.
use Quoin\Export\{FidelityReport, PdfOptions};
$options = new PdfOptions(onWarning: function (string $message, ?FidelityReport $report = null): void {
if ($report !== null) {
error_log("{$report->level->name} {$report->feature} at {$report->path}");
}
});Strict mode
To fail rather than lose content silently, turn on strict mode with strict: true in the export options, or 'strict' => true in the Laravel config. An export that would drop content then throws UnsupportedFeature instead. That includes a PDF with characters no font has, which would print as empty boxes (see Fallback fonts). Approximations are still allowed.
Strict mode works well in tests: a template that starts losing content fails the build instead of shipping.