Text
Text is measured with the embedded font's own metrics, so line breaks land where they should. Lines wrap between words, justified text stretches the spaces between words, and bold or italic runs keep their style when they wrap onto the next line.
Paragraphs and headings
| PHP | Blade | Use it for |
|---|---|---|
Text::make('…') | <x-doc::text> | Plain text in whatever style it inherits. |
Text::p('…') | <x-doc::p> | A paragraph, using the theme's paragraph style. |
Text::h1('…') to h4 | <x-doc::h1> to <x-doc::h4> | Headings. They stay on the same page as the block after them (see below). |
Headings keep with the next block by default, so a heading isn't left alone at the bottom of a page. Turn that off with ->keepWithNext(false) in PHP, or :keep-with-next="false" in Blade. In Word the heading paragraph gets keep-with-next, and in HTML it gets break-after: avoid. If a heading and the block after it can't fit on one page together, the heading still ends up alone.
To make text a heading without the h1 to h4 look, use Text::make('…')->asHeading(2) (PHP only). It gets a bookmark and a table of contents entry, an h2 tag in HTML and a Heading 2 style in Word, but keeps its own style. Unlike the presets, it doesn't keep with the next block unless you add ->keepWithNext(). headingLevel() returns a text's level, 1 to 4, or null when it isn't a heading.
Font, size, weight, color and alignment are inherited, so text follows what you set on its box:
<x-doc::column color="slate-600" font-size="9pt">
<x-doc::text>Both lines inherit the color and size.</x-doc::text>
<x-doc::text bold align="right">This one is bold and right-aligned.</x-doc::text>
</x-doc::column>use Quoin\{Column, Document, Page, Text};
use function Quoin\pt;
$document = Document::make(Page::letter()->body(
Column::make(
Text::make('Both lines inherit the color and size.'),
Text::make('This one is bold and right-aligned.')->bold()->right(),
)->color('slate-600')->size(pt(9)),
));On text tags, align and size are shorthand for text-align and font-size. On boxes, align positions the children instead.
Text that isn't valid UTF-8
Text that isn't valid UTF-8 (a database column in the wrong encoding, say) doesn't stop the export. Each bad byte becomes the replacement character, and the node gets one approximated note, which makes strict mode say so. The same goes for link text, table cells, code blocks and equations. Document metadata and PageNumber formats have no node to carry a note, so bad bytes there throw InvalidValue.
Keeping spaces and line breaks
By default runs of whitespace collapse to one space and a newline is a space. The white-space style attribute (Style::make(whiteSpace: WhiteSpace::PreWrap) in PHP) changes that. It takes normal (the default) or pre-wrap, and it is inherited, so it can be set on a box or on a single span.
Invisible formatting characters, common in text pasted from Word or a CMS (soft hyphens, zero-width joiners and spaces, direction marks, word joiners, byte order marks), are not drawn. The line and paragraph separators U+2028 and U+2029 are treated as newlines.
Under pre-wrap:
- spaces are kept, one for each space in the text, including a line's leading spaces;
- a newline (
\n,\r\nor\r) starts a new line; - a tab moves to the next multiple of four space widths, counted from the start of the line;
- a line longer than the box still wraps, at a space where it can and anywhere otherwise. The spaces at a wrap point are dropped rather than carried to the next line, but the spaces that start a line of the source stay;
- justified text is not stretched on these lines, since their spaces are layout.
A pre-wrap span inside normal text keeps its own spaces while the text around it collapses. In HTML a pre block is written as <pre> and inline code as <code>, with white-space: pre-wrap and tab-size: 4. In Word the spaces are kept, tabs become real tabs and line breaks become w:br; Word's tab stops differ from four space widths, so tabbed text can line up differently there than in the PDF.
In Blade, <x-doc::pre> makes a block in the pre style (monospace, pre-wrap) and <x-doc::code> an inline code span inside a text tag. Both take their content literally, so a variable echoed with {{ $code }} keeps its <, & and quotes:
<x-doc::p>Call <x-doc::code>render()</x-doc::code> once.</x-doc::p>
<x-doc::pre>
if ($a < $b && $c) {
echo "ok";
}
</x-doc::pre>In PHP, Span::code() makes the same inline code span, and Text::code() is a text that is only that span. Neither reads markup, so there is nothing to escape:
use Quoin\{Span, Text};
Text::make('Call ')->append(Span::code('render()'), ' once.');
Text::code('/v2/shipments');The result is identical to <x-doc::code> and to <code> in markup, in the PDF, in HTML and in Word.
Code blocks
A code block is a pre block with a language: it is colored by a TextMate theme and carries a small label with the language's name. Highlighting uses Phiki, which is optional:
composer require phiki/phiki<x-doc::pre language="php">
$total = array_sum($prices);
echo "Total: {$total}";
</x-doc::pre>use Quoin\{Document, Page};
use Quoin\Decorator\CodeBlock;
$document = Document::make(Page::letter()->body(
CodeBlock::make('$total = array_sum($prices);')->language('php'),
));Blade content is literal, as for any pre. {{ $code }} comes out exactly as the variable's value.
The language name can be an alias: bash, sh, shell and zsh all highlight as shell, js as JavaScript, ts as TypeScript, py as Python and yml as YAML.
Without Phiki, or for a language it doesn't know, the block is still drawn, as plain text. An unknown theme is replaced by the default theme and the code is still highlighted. In all three cases the export reports "dropped syntax highlighting" (for a missing package, the note says to install phiki/phiki), and strict mode throws instead.
Labels
The label is the language's display name in upper case, so language="php" shows PHP. label replaces it, and shows your text as written. false turns it off:
<x-doc::pre language="json" label="composer.json">{ "name": "acme/app" }</x-doc::pre>
<x-doc::pre language="json" :label="false">{ "name": "acme/app" }</x-doc::pre>In PHP, that is ->label('composer.json') and ->label(false). The plain words text, plaintext, txt and plain give a TEXT label and no colors. nohighlight and no-highlight give neither a label nor colors.
Looks
By default the label sits at the top right of the box, on a small line above the code. Two variants move it:
strip: a header bar across the top of the box, with the label in it.caption: the label above the box, and a rule down the left side instead of a border.
<x-doc::pre language="php" variant="strip">$a = 1;</x-doc::pre>In PHP use ->variant('strip') or ->variant('caption'); the two can't be combined. Set a default for every block with quoin.code.variant in Laravel. In plain PHP there is no document-wide default: pass new CodeHighlighting(variant: 'caption') to each block with ->highlighting(), or to Markup with new MarkupOptions(code: new CodeHighlighting(variant: 'caption')).
Keeping a block on one page
A block that would straddle a page break is split like any other text. To move it to the next page whole, use ->keepTogether() in PHP, or keep-together on <x-doc::pre>:
<x-doc::pre language="php" keep-together>$a = 1;</x-doc::pre>A block taller than a page still splits. In Word the default look keeps its lines together, and strip keeps its header bar with the code.
Themes and colors
The colors come from the TextMate theme: the block's background and text, and every token. The default theme is quoin-light. Pick another per block, or for all of them:
<x-doc::pre language="php" theme="github-dark">$a = 1;</x-doc::pre>use Quoin\Code\CodeHighlighting;
use Quoin\Decorator\CodeBlock;
CodeBlock::make('$a = 1;')->language('php')->theme('github-dark');
// every block that gets this configuration
CodeBlock::make('$a = 1;')->language('php')->highlighting(new CodeHighlighting(theme: 'nord'));Phiki bundles many themes and languages, among them github-light, github-dark, dracula, nord, one-dark-pro and solarized-light. The full lists are in Phiki's documentation. An unknown theme falls back to the default, with a "dropped syntax highlighting" note.
A document or page can set the default for blocks that don't name a theme: codeTheme in a ThemeOverride, or code_theme in a Laravel :theme. See Changing the theme for one document or page.
The muted label and border colors are worked out from the brightness of the theme's background, so a dark theme gets a light label. Geometry (padding, radius, the label's size) comes from the code-block named styles, and the block's own style, such as ->background() or background="…", overrides the theme's colors. To recolor every block, pick or write a theme.
Your own grammars and themes
Register a grammar (a TextMate grammar JSON file), a theme (a VS Code or TextMate theme JSON file), an alias, or an injection grammar on the highlighter:
// config/quoin.php
'code' => [
'theme' => 'my-theme',
'grammars' => ['demo' => resource_path('grammars/demo.tmLanguage.json')],
'themes' => ['my-theme' => resource_path('themes/my-theme.json')],
'aliases' => ['dm' => 'demo'],
'injections' => [
['path' => resource_path('grammars/todo.injection.json'), 'into' => ['source.demo', 'source.php']],
],
],use Quoin\Code\{CodeHighlighting, PhikiHighlighter};
use Quoin\Decorator\CodeBlock;
$highlighter = (new PhikiHighlighter())
->grammar('demo', 'grammars/demo.tmLanguage.json')
->theme('my-theme', 'themes/my-theme.json')
->alias('dm', 'demo')
->injection('grammars/todo.injection.json', ['source.demo', 'source.php']);
$block = CodeBlock::make('demo text')
->language('dm')
->highlighting(new CodeHighlighting($highlighter, theme: 'my-theme'));Register on your own new PhikiHighlighter() and pass it to new CodeHighlighting($highlighter, ...), as above. Don't register on the shared default (CodeHighlighting::default()->highlighter()): it is one instance for the whole process, so everything you add would reach every document after it.
An injection grammar (VS Code style, with an injectionSelector and patterns) is merged into each grammar listed in into, named by scope. It applies when one of those is the block's language, not where that grammar is only embedded inside another. Register the host grammars first (in config, grammars is read before injections); bundled ones are already there. A registered grammar can be embedded in another by its scope name. A path that doesn't exist, or a file that isn't a valid grammar or theme, throws when the highlighter is built, and in Laravel the message names the config key, such as quoin.code.grammars.demo.
In markup
Markup::html() and <x-doc::markup> turn <pre><code class="language-php"> into a code block, using the document's defaults (theme, variant, registered grammars). lang-php works too, and so does the class on the pre. Tags inside the code are dropped and their text is kept, with an approximated note for anything other than span, code and br; <br> becomes a newline. To keep these as plain pre blocks, turn it off: new MarkupOptions(code: false) in PHP, or 'markup' => ['highlight' => false] in Laravel. In plain PHP, set the defaults for these blocks with new MarkupOptions(code: new CodeHighlighting(theme: 'github-dark', variant: 'strip')).
Word and HTML
In Word, the default look is shaded, bordered paragraphs, and strip and caption are tables. In HTML, a code block is a <pre><code> with colored spans, and class="language-php" on the <code> when there is a language.
Word can't round corners, so the default look's radius is reported as dropped (strip has it too; caption has none). Strict Word export throws for it unless you set radius: 0 on the block. The label's weight of 600 is reported as approximated, which strict export allows.
Inline formatting
Text tags in Blade, and Text::markup() in PHP, understand a handful of inline tags: <b>, <i>, <u>, <s>, <mark>, <span> with style attributes, <a href>, <br>, <code> and <badge>. Any other tag throws an error.
<x-doc::text>
Plain, <b>bold</b>, <i>italic</i>, <span color="indigo-600">colored</span> and a <mark>highlighted</mark> word.
</x-doc::text>use Quoin\{Document, Page, Text};
$document = Document::make(Page::letter()->body(
Text::markup('Plain, <b>bold</b>, <i>italic</i>, <span color="indigo-600">colored</span> and a <mark>highlighted</mark> word.'),
));<mark> gives its text a yellow-200 background. <code> sets it in the monospace font with the code style. In PHP, Span::code($text) does the same for literal text, without markup.
A span whose style has horizontal padding or a border, such as a code style you've given padding in your theme, is drawn as a small box in the line, with its background and border around the padded text.
<badge> draws a small pill in the line. It takes type (neutral, note, tip, warning, danger or a tone you define) and variant, and its label is plain text with no tags inside. In PHP, Span::badge($text, $tone, $variant) builds one without markup. See Inline badges.
In PHP you can also build the runs yourself:
use Quoin\{Document, Page, Span, Text};
use Quoin\Style\Style;
$document = Document::make(Page::letter()->body(
Text::spans(
Span::text('Built from '),
Span::text('spans', new Style(fontWeight: 700)),
Span::break(),
Span::text('after a line break.'),
),
));A span can also carry a theme style name and a base style (what was set outside it). The span's own style wins over the named style, which wins over base. Markup sets these; you rarely need to.
This page is about text you write in your templates. For HTML from a rich text editor, or plain text from a form, see Rich text.
Lists
ListNode::ordered() and ListNode::unordered() take a list of items. Strings and other components are wrapped in a list item for you. An item can hold any content, including another list.
<x-doc::ol start="3" marker="upper-alpha">
<x-doc::li>
Plan
<x-doc::ul><x-doc::li>Scope</x-doc::li><x-doc::li>Budget</x-doc::li></x-doc::ul>
</x-doc::li>
<x-doc::li>Build</x-doc::li>
<x-doc::li value="10">Ship</x-doc::li>
</x-doc::ol>use Quoin\{Document, ListItem, ListNode, Page};
use Quoin\Style\ListMarker;
$document = Document::make(Page::letter()->body(
ListNode::ordered(
ListItem::make('Plan', ListNode::unordered('Scope', 'Budget')),
'Build',
ListItem::make('Ship')->withValue(10),
)->start(3)->marker(ListMarker::UpperAlpha),
));If you don't pick a marker, it changes with the nesting depth: numbered lists go 1., a., i. and bulleted lists go •, ◦, ▪. Markers are right-aligned, so 9. and 10. line up.
| Marker | Looks like |
|---|---|
decimal, lower-alpha, upper-alpha, lower-roman, upper-roman | 1. a. A. i. I. |
disc, circle, square | • ◦ ▪ |
none | no marker, but the indent stays |
A long list item can split across pages, and its marker always stays with the first line.
A top-level list has the theme's paragraph spacing after it. If the last item already ends with that spacing, for example because it ends in a paragraph, the list doesn't get it twice. Nested lists add none, and neither does a list that is the last thing in a table cell, or in a box with padding, a border or a background, since the box's own edge follows it there. A list with a margin set keeps the spacing that margin gives it.
In Word export, lists are real Word lists, except a list with marker none, which stays as indented paragraphs. Press Enter in Word and the list continues, and renumbering and the bullet and number buttons work. Word draws the markers its own way (left-aligned), unlike the right-aligned markers in the PDF. A very wide label, such as VIII. or 100. and beyond, pushes the item's text to the next tab stop in Word, and alphabetic numbering past z follows Word (aa, bb, and so on). Nested lists sit one level deeper, and extra blocks in an item, such as paragraphs and tables, stay indented under it. An item whose number breaks the sequence partway through a numbered list (ListItem::withValue() or <li value>) starts a new Word list from that item on, and this is reported as approximated. A value on the first item is the list's start number. Bulleted lists ignore these values. Lists whose numbers Word can't show, meaning any number below 1 or roman numerals above 3999, keep typed markers instead, also reported as approximated.