Configuration
To customize the package, publish the config file to config/quoin.php:
php artisan vendor:publish --tag=quoin-configDocuments
| Key | Default | Description |
|---|---|---|
prefix | 'doc' | The Blade tag prefix. Lowercase letters, digits and dashes only. Read when the app boots. |
paper | 'a4' | The page size when <x-doc::page> doesn't set one. A paper name, or a width and height like '8.5in 11in'. |
margin | '20mm' | The page margin when <x-doc::page> doesn't set one. |
theme | [] | Document defaults: font_family, font_size (in points), color, line_height and mono_family (the font the monospace keyword and code use; default Cousine). Other keys throw an error that names the key (code_theme belongs in code.theme, styles in styles). The default code theme is code.theme. A document or page can override these: see Changing the theme for one document or page. |
styles | [] | Named styles, using the same names as tag attributes. |
fonts | [] | Extra font families. See Fonts. |
fallback_fonts | [] | Families to try, in order, for characters the main font doesn't have. |
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. See Equations. |
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. See Word font names. |
bookmarks | true | Builds the PDF's bookmarks panel from headings. false leaves it empty. |
image_path | null | The base directory for relative <x-doc::image src> paths. null means public_path(). |
cache_dir | null | Where to cache parsed fonts. null uses storage/framework/cache/quoin, and false turns the disk cache off. |
Errors
| Key | Default | Description |
|---|---|---|
overflow | null | 'throw' or 'clip'. null throws in local and testing and clips everywhere else. See Content that doesn't fit. |
strict | false | When true, an export throws instead of dropping content. Turn it on in tests. See Strict mode. |
Word
| Key | Default | Description |
|---|---|---|
docx.toc_page_numbers | true | Lays out the pages to fill in a table of contents' page numbers, which costs about as much as a PDF export. false skips it: entries show without numbers until the reader updates the field in Word. |
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. Set QUOIN_RSVG_CONVERT=/usr/bin/rsvg-convert in .env. null or empty uses Imagick. See SVG in Word. |
HTML
| Key | Default | Description |
|---|---|---|
html.fonts | 'none' | 'none', 'embed', 'link' or 'sources'. See Fonts in HTML. |
html.font_url | null | A FontUrlResolver class. Required when fonts is 'link'. |
html.image_url | null | An ImageUrlResolver class. null embeds images as data URIs. |
html.inline_svgs | false | true writes SVGs into the page as markup so their text uses the page's fonts. Use only when you trust every SVG: inline SVG runs in the page. See Inline SVGs. |
html.font_sources | [GoogleFonts::class] | The font sources to check, in order, when fonts is 'sources'. |
html.google_fonts.host | 'https://fonts.googleapis.com' | Use '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 for every family, or a list of the families to load. |
html.local_fonts.mode | 'embed' | 'embed' or 'link'. |
html.local_fonts.families | null | null for every registered family, or a list. |
Resolvers are class names, because closures can't survive php artisan config:cache; a closure throws an error naming the key. The container builds each class, so constructor injection works.
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 embeds
}
}Markup
| Key | Default | Description |
|---|---|---|
markup.images | null | An ImageResolver class. null treats every <img> as missing. |
markup.styles | 'theme' | 'theme' or 'original'. See Rich text. |
markup.blank_paragraphs | 'drop' | 'drop' or 'keep'. |
markup.toc | true | false keeps the headings markup converts out of tables of contents. See Rich text. |
markup.highlight | true | false keeps <pre><code class="language-x"> as plain pre blocks instead of code blocks. |
Markup images
A resolver for a rich text 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;
}
}'markup' => ['images' => \App\Markup\EditorImages::class],A single tag can use a different resolver with the images attribute: <x-doc::markup :html="$body" images="App\Markup\LegacyImages" />. The class must implement Quoin\Laravel\Markup\ImageResolver, like the config value. images="none" (lower case only) turns images off for that tag, so each image shows its alt text, as for a missing image.
Within one markup conversion the resolver is called once for each distinct src (trimmed of surrounding whitespace); later images with the same src reuse the answer, including a null.
A resolver is built once per request, queue job or Octane request, and every markup tag in it shares that instance, whether the class comes from the config or from a tag's images attribute. A cache in a property lasts that long; for longer, use Laravel's cache.
Code
Syntax highlighting for code blocks needs phiki/phiki.
| Key | Default | Description |
|---|---|---|
code.theme | null | The default theme. null is quoin-light. A name from Phiki's bundled themes or code.themes. |
code.variant | null | null, 'strip' or 'caption': the look of 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. |
A path that can't be read, or a grammar or theme that isn't valid, throws an error that names the key, such as quoin.code.grammars.demo.
Preview
| Key | Default | Description |
|---|---|---|
preview.enabled | env('QUOIN_PREVIEW', false) | Turns on the preview routes. |
preview.path | '_quoin' | The URL prefix for the preview routes. |
Mistakes in the html.*, markup.* and code.* settings are reported the first time they're used, not when the app boots.