quoin / laravel
Blade views to page-aware PDF, Word, and HTML documents, laid out by quoin/core.
Requires
- php: ^8.4
- illuminate/console: ^12.0|^13.0
- illuminate/http: ^12.0|^13.0
- illuminate/mail: ^12.0|^13.0
- illuminate/routing: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
- illuminate/view: ^12.0|^13.0
- quoin/core: ^0.16
- quoin/math: ^0.16
Requires (Dev)
- bacon/bacon-qr-code: ^3.1
- orchestra/testbench: ^11.3
- phiki/phiki: ^2.2
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^13.4
- quoin/docx: ^0.16
Suggests
- phiki/phiki: Syntax highlighting in code blocks (TextMate grammars and themes)
- quoin/docx: Word (.docx) export: ->docx() and ?format=docx previews
Provides
None
Conflicts
None
Replaces
None
README
quoin/laravel
Blade components for Quoin: <x-doc::*> tags compile into the layout engine and out to PDF, HTML or Word. Not HTML-to-PDF.
Documentation: one-learning-community.github.io/quoin/laravel
Status: 0.16, before 1.0. Until 1.0 a minor version may change the API; patch versions won't.
Install
composer require quoin/laravel
Requires PHP 8.4+, ext-zlib, ext-mbstring, ext-dom and Laravel 12 or 13. The service provider and the Quoin facade are auto-discovered.
Quick start
{{-- resources/views/pdf/hello.blade.php --}} <x-doc::document title="Hello"> <x-doc::page> <x-doc::h1>Hello, {{ $name }}</x-doc::h1> <x-doc::p>Rendered by Quoin.</x-doc::p> </x-doc::page> </x-doc::document>
use Quoin\Laravel\Facades\Quoin; Route::get('/hello', fn () => Quoin::view('pdf.hello', ['name' => 'Ada'])->pdf()->download('hello.pdf'));
A view must have exactly one <x-doc::document> root. Quoin::view($view, $data) returns a PendingDocument; ->document() gives the core Document and ->pdf() a PendingOutput with download($filename), streamDownload($filename) (a streamed response that renders as it's sent; Livewire and Filament actions need it), inline($filename), save($path), store($path, $disk = null) (a Laravel filesystem disk), toString() and output(). The filename defaults to document.pdf. A PendingOutput returned from a route renders inline. Quoin::make($document) wraps a Document you built in PHP the same way. ->encrypt('secret') (or an Encryption with custom permissions) returns a copy whose PDF opens only with that password; HTML is not affected.
Full examples: examples/laravel (invoice, transcript, report). Content inside <x-doc::document> may also contain your own Blade components, which can themselves contain <x-doc::*> tags.
Configuration
php artisan vendor:publish --tag=quoin-config
This publishes config/quoin.php:
| Key | Default | Meaning |
|---|---|---|
prefix |
'doc' |
Blade tag prefix (<x-doc::page>): lowercase letters, digits and dashes. Read at boot |
paper |
'a4' |
Page size when <x-doc::page> has no size: a0–a6, b4, b5, letter, legal, tabloid, executive, or a width and height such as '8.5in 11in' |
margin |
'20mm' |
Page margin when <x-doc::page> has no margin |
fonts |
[] |
Extra font families, see Fonts |
fallback_fonts |
[] |
Family names tried, in order, for glyphs the primary font lacks |
math_font |
null |
Path of the TrueType math font equations use in PDF and HTML; null is the bundled STIX Two Math. Relative paths start at base_path(). A CFF font throws an error |
font_word_names |
[] |
The name Word uses for a family, as 'Family' => 'Word name'. The family must be bundled or in fonts, and the match ignores case. Cousine is Courier New unless set here |
theme |
[] |
Defaults: font_family, font_size (points, number), color, line_height (number), mono_family (the family the monospace font keyword and the pre and code styles use; bundled or in fonts; default Cousine). The default code theme is code.theme. A document or page can override these, see Theme per document or page |
styles |
[] |
Named styles |
overflow |
null |
'throw', 'clip', or null = throw in local/testing, clip elsewhere |
strict |
false |
true makes an export throw UnsupportedFeature for content a format cannot render, instead of dropping it with a warning. Consider true in tests |
html.fonts |
'none' |
Fonts in HTML output: 'none' (a font stack ending in a generic family that matches the font's class, small files), 'embed' (base64 @font-face, large files), 'link' (@font-face with URLs from html.font_url; requires it) or 'sources' (see Font sources) |
html.image_url |
null |
Class name implementing Quoin\Laravel\Html\ImageUrlResolver; null embeds images as data URIs (see HTML URLs) |
html.font_url |
null |
Class name implementing Quoin\Laravel\Html\FontUrlResolver; required when html.fonts is 'link' |
html.font_sources |
[GoogleFonts::class] |
Used when html.fonts is 'sources': an ordered list of class names implementing Quoin\Html\FontSource |
html.google_fonts.host |
'https://fonts.googleapis.com' |
Host of the GoogleFonts source; 'https://fonts.bunny.net' for Bunny Fonts |
html.google_fonts.display |
'swap' |
font-display: auto, block, swap, fallback or optional |
html.google_fonts.families |
null |
null = every family, or a list of family names (allowlist) |
html.local_fonts.mode |
'embed' |
LocalFonts source: 'embed' (base64) or 'link' (URLs from html.font_url; requires it) |
html.local_fonts.families |
null |
null = every registered family, or a list of family names |
markup.images |
null |
Class name implementing Quoin\Laravel\Markup\ImageResolver; null treats every <img> in markup as missing (see Rich text) |
markup.styles |
'theme' |
'theme' (HTML gives structure, the theme styles it) or 'original' (inline style="" applied on top) |
markup.blank_paragraphs |
'drop' |
'drop' or 'keep' paragraphs that hold only or <br> |
markup.toc |
true |
false keeps converted headings out of tables of contents; they keep their look and bookmarks |
docx.toc_page_numbers |
true |
Word export lays out the pages to fill in a table of contents' page numbers (about the cost of a PDF export); false skips that, and entries show without numbers until the reader updates the field |
markup.highlight |
true |
false keeps <pre><code class="language-x"> as plain pre blocks instead of code blocks |
code.theme |
null |
Default code theme. null is quoin-light; otherwise a name from Phiki's bundled themes or code.themes |
code.variant |
null |
null, 'strip' or 'caption': the look of code blocks that don't set a variant |
code.grammars |
[] |
'name' => path to a TextMate grammar JSON file |
code.themes |
[] |
'name' => path to a TextMate theme JSON file |
code.aliases |
[] |
'alias' => 'language' |
code.injections |
[] |
A list of ['path' => …, 'into' => ['source.x', …]]: a VS Code style injection grammar, merged into the grammars with those scope names. Grammars are registered first, so into can name one from code.grammars |
docx.rsvg_convert |
env('QUOIN_RSVG_CONVERT') |
Absolute path to rsvg-convert, which then draws SVG in Word export, so Imagick isn't needed for it. null or empty uses Imagick |
bookmarks |
true |
Headings and bookmark="…" build the PDF's bookmarks panel; false leaves it empty |
image_path |
null |
Base directory for relative <x-doc::image src> and <x-doc::svg src>; null = public_path() |
cache_dir |
null |
Parsed-font cache directory: null = storage_path('framework/cache/quoin'), false = no disk cache, or a path (see core's "Font cache") |
preview.enabled |
env('QUOIN_PREVIEW', false) |
Enable preview routes |
preview.path |
'_quoin' |
URL prefix for preview routes |
HTML output
The same document exports to HTML. ->html() shares the theme, fonts, named styles and strict setting with ->pdf().
// A route: a full HTML page (Content-Type text/html; charset=UTF-8) return Quoin::view('pdf.invoice', $data)->html(); // Download or save Quoin::view('pdf.invoice', $data)->html()->page()->download('invoice.html'); Quoin::view('pdf.invoice', $data)->html()->page()->save(storage_path('invoice.html')); // The embeddable fragment as a string or file $fragment = Quoin::view('pdf.invoice', $data)->html()->fragment()->toString();
Inside another Blade view, {{ $doc->html() }}, {!! $doc->html() !!} and (string) $doc->html() all give the embeddable fragment (one .quoin element, no <html>), where $doc is Quoin::view(...) or Quoin::make($document). Returning ->html() from a route sends the full page. PendingHtml has no toString(), save() or download() of its own, so a string never means two things: ->html()->page() and ->html()->fragment() each return a PendingOutput (toString(), save(), download(), inline(), default name document.html). HTML reports approximations through the same warning log as PDF. Every approximation is reported (for example fr column widths, the page box, and header and footer once per page), and HTML reports nothing as dropped, so strict does not throw for it.
HTML URLs
html.image_url and html.font_url name invokable classes, built by the container (constructor dependencies work). Use class names, not closures: a class name survives php artisan config:cache, and a closure in config is rejected with an error naming the key. Return null to embed an image as a data URI, or to skip a font face.
namespace App\Pdf; use Quoin\Image; use Quoin\Laravel\Html\ImageUrlResolver; final class CdnImageUrl implements ImageUrlResolver { public function __invoke(Image $image): ?string { ['kind' => $kind, 'value' => $value] = $image->source(); return $kind === 'file' ? asset('img/' . basename($value)) : null; // null = embed } } // config/quoin.php 'html' => ['fonts' => 'link', 'image_url' => \App\Pdf\CdnImageUrl::class, 'font_url' => \App\Pdf\CdnFontUrl::class],
Invalid html.* config is reported at the first ->html() export, not at boot.
Font sources
html.fonts = 'sources' sends each font family to the first source in html.font_sources that accepts it. It works with no other setting: the default list is Google Fonts, so each family becomes a <link> to fonts.googleapis.com. For how sources, answers and fallbacks work, see "Fonts in HTML" in the core README.
// Bunny Fonts instead of Google: a host change 'html' => ['fonts' => 'sources', 'google_fonts' => ['host' => 'https://fonts.bunny.net']], // Fonts registered in quoin.fonts embedded; anything else from Google 'html' => [ 'fonts' => 'sources', 'font_sources' => [\Quoin\Html\LocalFonts::class, \Quoin\Html\GoogleFonts::class], 'local_fonts' => ['families' => ['Acme']], // null = every registered family ],
A custom source is a class implementing Quoin\Html\FontSource, built by the container, so constructor dependencies work:
use Quoin\Html\{FontAnswer, FontRequest, FontSource}; final class BrandFonts implements FontSource { public function __invoke(FontRequest $request): ?FontAnswer { return $request->family === 'Acme' ? FontAnswer::stylesheet('https://brand.example/fonts.css') : null; // null = ask the next source } } 'font_sources' => [\App\Pdf\BrandFonts::class, \Quoin\Html\GoogleFonts::class],
- Order. The first source that answers wins, so list specific sources first and catch-all hosts such as Google last.
- Privacy. With
GoogleFontsthe visitor's browser fetches the stylesheet and fonts from the host, and so sends it their IP address. A German court held this can breach data protection law without consent (LG München I, 3 O 17493/20). Bunny Fonts is a host that states it does not log IP addresses, but the request still reaches a third party and this is not a compliance guarantee. The fully private routes areLocalFonts(embed, or link to your own files) and the'embed'and'link'modes. - CSP. If your site sends a Content-Security-Policy, allow:
style-srcfor the stylesheet host (fonts.googleapis.comfor Google,fonts.bunny.netfor Bunny);font-srcfor the font domain (fonts.gstatic.comfor Google,fonts.bunny.netfor Bunny); andfont-src data:for embedded faces (local_fontsin its defaultembedmode). - Config is checked lazily.
font_sourcesis read only whenhtml.fontsis'sources', andgoogle_fontsandlocal_fontsonly when their class is in the list, at the first->html()export. Class names only: closures are rejected naming the key and index, for examplequoin.html.font_sources.1.
Preview routes accept ?format=pdf (default), ?format=html or ?format=docx (with quoin/docx); any other value is a 404.
Word output
With quoin/docx installed (composer require quoin/docx), ->docx() exports the same document as a Word file, sharing the theme, fonts, named styles and strict setting with ->pdf():
return Quoin::view('pdf.invoice', $data)->docx()->download('invoice.docx');
It returns a PendingOutput (default name document.docx). Without the package, the export throws MissingExporter with the command to install it. Preview routes accept ?format=docx. Opacity is blended onto what lies beneath. QR codes and SVG are drawn into pictures: SVG with rsvg-convert (recommended; set docx.rsvg_convert) or Imagick, and styled QR codes need Imagick. What Word can't show (corner radius and more) is reported through the same warning log, and strict throws on anything left out. See the Word export guide.
Tags
Style attributes (next section) work on every tag marked "style" below. Values are plain strings (gap="8pt"), or bound PHP values (:gap="$gap"). Boolean attributes can be written bare (bold) or bound.
| Tag | Own attributes | Notes |
|---|---|---|
<x-doc::document> |
title, author, subject, keywords, lang |
Root. Children must be <x-doc::page>; with no page, content gets an implicit page. No style attributes. |
<x-doc::page> |
size (a paper name or "<width> <height>"), orientation (portrait/landscape), margin, header-gap, footer-gap, mirror, template or template-data, template-page, template-password |
Slots: <x-slot:header>, <x-slot:footer>, <x-slot:first-header>, <x-slot:first-footer>, <x-slot:even-header>, <x-slot:even-footer>, <x-slot:background>, <x-slot:overlay>. An empty first- or even- slot means nothing on that page. Slot names also accept camelCase (<x-slot:firstHeader>); if both spellings are given, the later one wins. mirror (boolean) mirrors the left and right margins on even pages. template (a PDF under the image path) or template-data (its bytes) draws a page of a PDF behind the page and sizes the page from it, so size and orientation can't be used with it. No style attributes. |
<x-doc::place> |
x, y, anchor, width |
Only in <x-slot:overlay>. Puts its content at x, y: lengths from the page's top-left corner, or percentages of its width and height. anchor (top-left by default, top, top-right, left, center, right, bottom-left, bottom, bottom-right) is the point of the content placed there. width is a length or a percentage of the page width. No style attributes. |
<x-doc::view> |
align |
Style. Generic container. |
<x-doc::row> |
align |
Style. Lays children out horizontally. |
<x-doc::column> |
align |
Style. Lays children out vertically. |
<x-doc::text> |
align, size |
Style. Inline markup allowed: <b>, <i>, <u>, <s>, <mark>, <code>, <a href>, <br>, <span>, <badge type variant>. |
<x-doc::h1> ... <x-doc::h4> |
align, size |
Style. Heading presets. |
<x-doc::p> |
align, size |
Style. Paragraph preset. |
<x-doc::qr-code> |
value, level (L/M/Q/H), quiet-zone, shape (square/rounded/dots; the last two raise level to at least Q), eyes (square/dot/pointy), eye-color, gradient (two colors), gradient-type |
Style. A square QR code drawn as vectors in the text color; width sets its size (25mm by default). The styling attributes need composer require bacon/bacon-qr-code. No content. |
<x-doc::image> |
src, data, fit (contain/cover/fill) |
Style. Exactly one of src or data (raw bytes). PNG and JPEG; WebP, GIF, BMP and AVIF need ext-gd. An image taller than the page shrinks to fit unless it has an explicit height. Absolute and scheme paths (/x.png, C:\x.png, file://) are trusted as given; relative paths are contained to quoin.image_path (.. cannot escape it). Remote URLs are not supported. Never pass untrusted input to src. |
<x-doc::pdf-page> |
src or data, page, password |
Style. A page of an existing PDF, drawn as it is and sized like an image; relative src follows the same rules as <x-doc::image>. Left out of HTML exports. |
<x-doc::svg> |
src, data, or SVG markup inside the tag |
Style. Exactly one source. Drawn as vector paths and sized like an image; relative src follows the same rules as <x-doc::image>. Untrusted SVG is checked before it is drawn. |
<x-doc::link> |
href |
Style. Required href. |
<x-doc::table> |
columns, repeat-header |
Style. Children: one optional <x-doc::thead> first, then <x-doc::tr>. columns is a track list such as "3fr 25mm 20mm". repeat-header defaults to on. |
<x-doc::thead> |
none | Contains <x-doc::th>/<x-doc::td> cells (one header row) or <x-doc::tr> rows. |
<x-doc::tr> |
none | Style. Contains <x-doc::td>/<x-doc::th>. |
<x-doc::td> / <x-doc::th> |
colspan, rowspan, align (left/right/center/justify) |
Style. th is a header cell. |
<x-doc::ol> |
start, marker |
Style. Numbered list of <x-doc::li>. marker is any ListMarker value (decimal, lower-alpha, upper-alpha, lower-roman, upper-roman, disc, circle, square, none); unset follows nesting depth (1., a., i.). |
<x-doc::ul> |
marker |
Style. Bulleted list of <x-doc::li>. marker takes the same values as on ol; unset follows nesting depth (•, ◦, ▪). |
<x-doc::li> |
value |
Style. A list item; holds any block content, including nested lists. value sets its number. |
<x-doc::kv> |
label, total |
A row of <x-doc::key-value> or <x-doc::totals>. A label is required, as an attribute or a slot. total (a boolean) marks an emphasized row and is only allowed inside <x-doc::totals>. No style. |
<x-doc::totals> |
variant |
Style. Holds only <x-doc::kv> rows: labels on the left, amounts right-aligned. 45% wide at the right by default. See Decorators. |
<x-doc::stat> |
label, note, variant |
Style. The content is the value, with inline tags. label and note also work as slots. |
<x-doc::signature> |
name, role, date, variant |
Style. The content sits on the line (an image, a typed name, or nothing). name, role and date also work as slots. |
<x-doc::markup> |
html or text, or HTML in the slot (exactly one of the three; two sources throw), styles, blank-paragraphs, images, toc |
Converts HTML or plain text to nodes. Tags from this package in the slot are an error; components that render HTML are fine. See Rich text. A number is taken as its string. Inside a text tag it contributes inline content and inherits the text style. styles and blank-paragraphs override the config per use (with html; plain text ignores them). images names an ImageResolver class for this tag instead of markup.images, or none (lower case only) to show each image's alt text. toc="false" keeps every heading it converts out of tables of contents (markup.toc sets the default). |
<x-doc::pre> |
none | Style. A preformatted block in the pre style. The content is literal: tags are not parsed and entities are decoded. The first and last blank lines are dropped and the common leading indentation is removed. Components inside are an error. The tag is found by a compile step that runs on every Blade view in the app, so a PHP string holding a literal <x-doc::pre> tag in an ordinary (non-document) view gets an invisible U+E000 character after it. |
<x-doc::code> |
none | Style, applied to the span. Inline code in the code style, for use inside text tags. The content is literal text. |
<x-doc::node> |
node |
Embeds a PHP-built Node or Component (anything else throws InvalidValue). As a block among blocks. Inside a text tag a Text joins the line; a View is flattened into it like Markup::flatten() (block content approximated, images and other nodes dropped, each reported). |
<x-doc::spacer> |
size |
size="10mm" is a fixed gap; with no size it is flexible (grow, default 1). Only grow is accepted besides size/style. |
<x-doc::column-flow> |
columns, widths, column-gap, rule |
Style. Text set in columns, like Word's: content fills each column, then the next page, and the last page ends level. columns is 1 to 45 (default 2); widths="2 1" sets unequal columns as ratios; column-gap is one length, or one per gap (default 36pt); rule draws a line in each gap, bare or rule="1pt slate-400". gap spaces the children, as on any box. No border, background, padding or size: wrap it in a view for those. Not allowed inside a table cell, a row, another flow, or a header, footer, background or overlay. |
<x-doc::column-break> |
none | Sends what follows to the next column (from the last column, to the next page). Only inside <x-doc::column-flow>. |
<x-doc::equation> |
math or tex |
Style. A block equation. math is a string or a node built with Quoin\Math\Math; tex is a TeX string (exactly one of the two). A static tex containing {{ is Blade echo syntax, so bind it: :tex="'…'". In any tex attribute TeX's \\ line break must be written \\\\, or pass the TeX in a variable. Static quote style (tex="…" or tex='…') doesn't matter, but never use a double-quoted PHP string in a bound :tex: PHP turns \f, \n, \t and similar into control characters and interpolates $ variables. No content. Inside a text tag it is an error; use <x-doc::math>. |
<x-doc::math> |
math or tex |
Inside a text tag, an inline equation (Span::math()), with no style attributes. Anywhere else it is a block equation, like <x-doc::equation>. No content. It can't sit inside a raw inline HTML tag (<b>, <a>); that throws. |
<x-doc::page-number> |
format, align, size |
Style. format uses {page} and {total}; no content allowed. |
<x-doc::toc> |
levels, title, leaders |
Table of contents. levels="2" or "1-3" (1 to 4); title is a line above the list; leaders (default on) draws dot leaders; no content allowed. Leave a heading out with toc="false". |
<x-doc::page-break> |
none | Forces a new page. |
On row, column and view, align is a shorthand for align-items. On text tags, align is text-align and size is font-size. Every style-capable tag also accepts style="name" (a named style).
Style attributes
These attributes are accepted by every tag marked "style" above. Lengths are pt, mm, cm, in or px, or relative to the element: em (its font size) and lh (its line height, font size × line-height), so padding="0.5em" or min-height="4lh" follow the theme; percentages are where noted; colors are palette names such as slate-500, hex, or other forms Color::parse accepts.
| Attribute | Example | Notes |
|---|---|---|
width, height, basis |
width="70mm" |
length, percentage or auto |
min-width, max-width, min-height, max-height |
max-width="80%" |
length or percentage |
padding, margin, border-width |
padding="12pt", margin="6pt 0 0 0" |
1 to 4 lengths (top right bottom left) |
border-color, background, color |
background="slate-50" |
color |
border-style |
border-style="dashed" |
solid, dashed |
radius |
radius="8pt" |
length |
opacity |
opacity="0.5" |
0 to 1 |
direction |
direction="column" |
row, column |
gap |
gap="8pt" |
length |
justify |
justify="space-between" |
start, end, center, space-between, space-around, space-evenly |
align-items, align-self |
align-items="center" |
start, end, center, stretch |
grow, shrink |
grow="1" |
number, 0 or more |
wrap |
wrap |
boolean |
font |
font="Merriweather" |
family name |
font-size |
font-size="9pt" |
length, above 0 |
weight |
weight="600" |
integer 1 to 1000 |
bold, italic, underline, strike |
bold |
boolean |
line-height |
line-height="1.4" |
number, above 0 |
letter-spacing |
letter-spacing="0.6pt" |
length |
text-align |
text-align="right" |
left, right, center, justify |
keep-together, keep-with-next |
keep-together |
boolean; do not split the block / stay on the page with the next block |
break-before, break-after |
break-before |
boolean; force a page break |
min-lines |
min-lines="2" |
integer 1 or more (widow/orphan control) |
bookmark |
bookmark="Summary" |
title for the PDF's bookmarks panel; headings get one automatically, :bookmark="false" removes it |
bookmark-level |
bookmark-level="2" |
integer 1 or more; nesting depth of the bookmark |
toc |
toc="false" |
boolean; false leaves a heading out of every <x-doc::toc> (it keeps its bookmark) |
Boolean values: bare attribute or true/1/false/0. Any attribute not listed here (or in the tag's own attributes) throws UnknownAttribute, with the tag named and a suggestion when one is close.
Theme per document or page
<x-doc::document :theme="[...]"> and <x-doc::page :theme="[...]"> override the theme for one document or one page, and Quoin::view(...)->theme([...]) does it from a controller:
<x-doc::document :theme="['font_size' => 11]"> <x-doc::page :theme="['font_family' => 'Merriweather']">…</x-doc::page> </x-doc::document>
Quoin::view('pdf.invoice', $data)->theme(['color' => $customer->brand_color])->pdf();
Keys are font_family, mono_family, font_size, color, line_height, code_theme and styles (in the quoin.styles shape); the first five work as in quoin.theme. Merriweather must be bundled or registered in fonts. Order: config, the view's document, the controller's ->theme(), then the page. Named styles merge onto the existing style (quoin.styles still replaces). ->theme() can change values and restyle existing names, but a new style name the view uses must be defined in config or in a :theme in the view. Headings take their look from h1 to h4 styles when defined.
Named styles
Define styles in config/quoin.php, using the same keys as tag attributes:
'styles' => [ 'panel' => ['padding' => '12pt', 'background' => 'slate-50', 'radius' => '8pt'], ],
<x-doc::column style="panel">...</x-doc::column>
The named style is the base; attributes written on the tag override it for any property both set.
Decorators
Ready-made pieces that give content a look (each takes a variant, which also applies the theme's <name>.<variant> styles for the parts it styles; built in are line on field, outline on badge, flat on card and large on section): card, callout, blockquote, section, field, choices, key-value, badge, stat, totals and signature. They are plain components, so they work in PDF and HTML, take the usual style attributes on their outer box, and get their look from named styles you can override. Decorator style names (card, card.title, callout.*, section.*, field.*, choice.*, key-value.*, badge.*, blockquote.*, stat.*, totals.*, signature.*) belong to the decorators: a theme or config style with the same name replaces the built-in one, so pick other names for your own styles.
<x-doc::card title="Respondent"> <x-doc::text>Jane Smith</x-doc::text> </x-doc::card> <x-doc::card><x-slot:title><x-doc::text>Rich <b>title</b></x-doc::text></x-slot:title> ... </x-doc::card>
A bordered box with an optional title strip. callout and badge share tone names, so you can pair them:
<x-doc::callout type="warning" title="Before you start">Answers cannot be changed.</x-doc::callout> <x-doc::badge type="tip">Agree</x-doc::badge>
callout types: note (default), tip, warning, danger. badge types: neutral (default), note, tip, warning, danger. A badge is a block that hugs its text. Inside a text tag it is an inline badge instead (<badge type="tip"> in markup; variant works too), with a plain-text label.
<x-doc::blockquote cite="Jane Smith, 2024">Quoted words.</x-doc::blockquote> <x-doc::section number="3" title="Search terms" rule keep-together> ...content... </x-doc::section> <x-doc::section number="3"><x-slot:title><x-doc::markup :text="$prompt" /></x-slot:title> ... </x-doc::section>
A section keeps its heading with the first of its content. The number is a string and no punctuation is added. The heading is always laid out as a row (number beside title); a direction in the section.heading style has no effect. An empty title or number is treated as unset.
heading="1" to heading="4" on a section or card makes its title a real heading (bookmark, table of contents entry, h tag in HTML, Heading style in Word) without changing its look. A numbered section's entry reads "3 Search terms". A heading tag inside the title slot doesn't do this, because the slot is joined into one line of text.
<x-doc::field label="Comments" placeholder="No response" lines="3">{{ $text }}</x-doc::field>
Without a label, style attributes apply to the box. With a label, they style the whole field (label and box together); style the box itself through the theme's field style.
A bordered box that shows placeholder when its content is empty (no children, or only whitespace). lines reserves that many lines of the field's own text inside its padding, so it follows the theme's font size and line height. A field whose lines don't fit in the space left on a page moves to the next page as a whole, as any box with min-height does.
<x-doc::choices type="checkbox" emphasize-selected> <x-doc::choice selected>Library catalog</x-doc::choice> <x-doc::choice>Web search</x-doc::choice> </x-doc::choices>
type is checkbox (default) or radio. Markers are drawn shapes, not glyphs, so they look the same in every font. Markers are sized from the text (0.75em) and centered in a slot one line tall, so they sit level with the first line of a label at any font size. <x-doc::choice> is only valid inside <x-doc::choices>.
<x-doc::key-value label-width="30%"> <x-doc::kv label="Respondent">Jane Smith</x-doc::kv> <x-doc::kv label="I can use this at work"><x-doc::badge type="tip">Agree</x-doc::badge></x-doc::kv> </x-doc::key-value>
Aligned label and value rows. label-width fixes the first column so long labels wrap.
<x-doc::stat label="Revenue" note="vs last month">$12,400</x-doc::stat> <x-doc::totals> <x-doc::kv label="Subtotal">$100.00</x-doc::kv> <x-doc::kv label="Tax">$8.00</x-doc::kv> <x-doc::kv label="Total" total>$108.00</x-doc::kv> </x-doc::totals> <x-doc::signature name="Jane Smith" role="Director" date="13 November 2026" />
stat is a panel with a small label, a large value and an optional note. totals is a block of label and amount rows, 45% wide at the right, where total marks an emphasized row. signature is a line to sign on, with the name, role and date beneath it; its content (an image, a typed name) sits on the line.
<mark> works in any text tag and in <x-doc::markup>: <x-doc::text>a <mark>key</mark> word</x-doc::text> paints a yellow-200 background behind the run. In <x-doc::markup :html>, <span style="background-color: ..."> keeps its own color only when markup.styles is 'original'; in 'theme' mode inline styles are ignored.
Built-in styles
Each decorator reads these names. Colors are palette names.
| Style | Default |
|---|---|
card, card.title, card.body |
1pt slate-300 border, 4pt radius; slate-100 bold title strip with 3pt corners; 10pt body padding |
callout, callout.<tone>, callout.title, callout.title.<tone> |
3pt left rule, tinted box in sky, emerald, amber or red (rule -500, background -50), bold title in the -800 shade |
blockquote, blockquote.cite |
3pt slate-300 left rule, italic slate-700; cite 0.9em slate-500, not italic |
section, section.heading, section.number, section.title, section.rule, section.body |
6pt gap, bold title, bold slate-500 number 18pt wide, 0.75pt slate-200 rule; the heading is always a row |
field, field.label, field.placeholder |
1pt slate-300 border, 3pt radius; 0.9em slate-600 label; italic slate-400 placeholder |
choice, choice.option, choice.marker, choice.marker.radio, choice.marker.selected, choice.mark, choice.mark.radio, choice.label.selected |
0.75em marker with 1pt slate-400 border, round for radio; selected border slate-800 and a 0.42em inner mark; selected label bold; 6pt between marker and label |
key-value, key-value.label, key-value.value |
no borders; slate-600 label |
badge, badge.<tone> |
0.9em bold pill in slate, sky, emerald, amber or red (background -100, text -800, border -300, which shows only with outline), aligned to the start so it hugs its text |
stat, stat.label, stat.value, stat.note |
slate-50 panel, 6pt corners, 10pt 12pt padding; label 0.75em bold slate-500; value 1.8em bold slate-900; note 0.8em slate-600 |
totals, totals.label, totals.value, totals.total-label, totals.total-value |
45% wide, aligned to the end, doesn't shrink; slate-600 labels, right-aligned values, 12pt between columns; total rows bold slate-900 1.1em with a 1pt slate-300 rule above |
signature, signature.line, signature.name, signature.role, signature.date |
216pt (3in) wide, kept together; line at least 30pt high with a 0.75pt slate-700 rule beneath; bold name; 0.85em slate-600 role and date |
field.line, badge.outline, card.flat, card.title.flat, section.large, section.title.large, section.number.large |
The built-in variants: field.line keeps only a 1pt slate-400 bottom rule; badge.outline has no fill and a 0.75pt border in the tone's color; card.flat is a slate-50 panel with no border; section.large sets the title and number at 1.35em |
Every value is listed in the decorator styles reference.
Restyle or add a tone
Define a style with the same name in config/quoin.php. It replaces the built-in one entirely, so restate every property you want:
'styles' => [ 'callout.warning' => ['border-color' => 'orange-500', 'background' => 'orange-50'], 'callout.success' => ['border-color' => 'green-600', 'background' => 'green-50'], 'callout.title.success' => ['color' => 'green-800'], ],
In PHP, $theme->withStyle('callout.warning', Style::make(...)) does the same. To add a tone, define callout.<tone> and callout.title.<tone> (as success above), then write type="success"; a badge tone needs badge.<tone>. Style names can also be combined in a style attribute, space-separated: style="callout callout.success".
Rich text from your database
<x-doc::markup> converts stored HTML or plain text into document nodes. Pass the value bound (:html), so Blade
does not escape it.
<x-doc::markup :html="$slide->body" /> <x-doc::markup :text="$prompt" /> <x-doc::markup :html="$slide->body" styles="original" blank-paragraphs="keep" />
Used inside a text tag it joins the line and inherits the surrounding style:
<x-doc::text bold>× <x-doc::markup :html="$label" /></x-doc::text>
To embed a node you built in PHP, use <x-doc::node :node="$node" />. Limitation: in Blade an inline tag cannot span
an embedded node. <x-doc::text><b>x <x-doc::node :node="$t"/> y</b></x-doc::text> throws " is not closed"; close
the tag on each side instead (<b>x </b><x-doc::node :node="$t"/><b> y</b>).
Images
Markup conversion never reads an <img src> itself. Name a resolver class in quoin.markup.images. It receives the trimmed
decoded src, once per distinct value in a markup conversion (later images with the same src reuse the answer, a null
included), and returns the image bytes, or null when the image is missing. The container builds it, so it can take
dependencies. src is untrusted user input: the resolver decides what may be read, so never pass it to a disk or the
filesystem unchecked. For example, an editor that stores uploads on the default disk and serves resized copies from
/public/images/{size}/files/uploaded/editor/...:
namespace App\Markup; use Illuminate\Support\Facades\Storage; use Quoin\Laravel\Markup\ImageResolver; final class EditorImages implements ImageResolver { public function __invoke(string $src): ?string { if (preg_match('#^/public/images/[^/]+/(files/uploaded/editor/.+)$#', $src, $m) !== 1) { return null; } // Reject NUL and any `..` segment: the disk would normalise `editor/../../private/x` to `private/x`. if (str_contains($m[1], "\0") || in_array('..', preg_split('#[/\\\\]#', $m[1]) ?: [], true)) { return null; } $disk = Storage::disk(); return $disk->exists($m[1]) ? $disk->get($m[1]) : null; } }
// config/quoin.php 'markup' => [ 'images' => \App\Markup\EditorImages::class, 'styles' => 'theme', 'blank_paragraphs' => 'drop', ],
A missing image (null, a throw, or bytes that are not a recognized image format) shows its alt text in italics, or
nothing without alt, and is reported. Invalid markup.* config is reported at first use.
What is converted and reported
The element mapping, style modes, supported CSS properties and the full report-level table are in
core's README. In short: structure comes from the HTML and the look from your theme
(styles="original" also applies inline style="": supported properties only, px at 0.75pt). Things that cannot be
drawn are reported through onWarning and the fidelity report. approximated ones (an iframe shown as a link, a missing
image shown as alt text, an unknown tag removed with its content kept) never fail a strict export. dropped ones (a
missing image without alt text, an unsupported link, an unsupported CSS declaration) do. Nesting deeper than 256
levels is flattened to text with one report. Known gap in original mode: CSS color keywords such as red and
hsl() are not recognized yet (!important is ignored).
Fonts
Inter (regular, bold, italic, bold italic) is bundled and always available. Register more families by path (relative paths resolve against base_path()):
'fonts' => [ 'Merriweather' => [ 400 => ['normal' => 'resources/fonts/Merriweather-Regular.ttf', 'italic' => 'resources/fonts/Merriweather-Italic.ttf'], 700 => ['normal' => 'resources/fonts/Merriweather-Bold.ttf'], ], ], 'fallback_fonts' => ['Noto Sans'], 'theme' => ['font_family' => 'Merriweather', 'font_size' => 10],
php artisan quoin:fonts:install "Merriweather" --weights=400,700 --italic downloads a family's TrueType files from Google Fonts into resources/fonts/<Family>/ (--path to change, --force to overwrite), saves the family's license beside them (OFL.txt, LICENSE.txt or UFL.txt, from Google's fonts repository) and prints the fonts entry to paste into the config. The files are downloaded once and committed with the app; rendering never touches the network.
php artisan quoin:fonts lists every available face and reports whether each file is ok, missing or invalid. A glyph missing from the primary family is looked up in fallback_fonts; if no family has it, a warning is logged ([quoin] ...).
Preview routes
For fast iteration on a layout, register a view with sample data (for example in a service provider) and enable previews:
Quoin::preview('pdf.invoice', fn () => ['invoice' => Invoice::factory()->make()]);
Set QUOIN_PREVIEW=true. Only in the local environment, GET /_quoin lists the registered views and GET /_quoin/{view} renders one inline.
Errors
Quoin\Exception\UnknownAttributeandQuoin\Exception\InvalidValue: reported with the tag (on <x-doc::td>), the attribute and, where possible, a suggestion.Quoin\Laravel\Exception\InvalidStructure: misplaced content, such as a<x-doc::tr>outside a table, a missing<x-doc::document>root, or an unknown page slot.Quoin\Exception\ImageUnreadable: thesrcfile is missing or cannot be read as an image.Quoin\Exception\LayoutOverflow: a block cannot fit on a page even after every permitted split. Controlled byoverflow: throw (default inlocal/testing) or clip.
Blade wraps exceptions thrown while rendering a view in Illuminate\View\ViewException; the original is its getPrevious().
Credits
The Blade tags compile to quoin/core, and every PDF is written by dskripchenko/php-pdf, by Denis
Skripchenko. Word output uses his dskripchenko/php-docx. Thank you to both projects.