Quoin
Guide
Laravel
Math
Reference
Examples
Gallery
Changelog
GitHub
Guide
Laravel
Math
Reference
Examples
Gallery
Changelog
GitHub
  • Laravel

    • Laravel
    • Configuration
    • Preview routes
    • Recipes
    • From Tailwind

Configuration

To customize the package, publish the config file to config/quoin.php:

php artisan vendor:publish --tag=quoin-config

Documents

KeyDefaultDescription
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_fontnullPath 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.
bookmarkstrueBuilds the PDF's bookmarks panel from headings. false leaves it empty.
image_pathnullThe base directory for relative <x-doc::image src> paths. null means public_path().
cache_dirnullWhere to cache parsed fonts. null uses storage/framework/cache/quoin, and false turns the disk cache off.

Errors

KeyDefaultDescription
overflownull'throw' or 'clip'. null throws in local and testing and clips everywhere else. See Content that doesn't fit.
strictfalseWhen true, an export throws instead of dropping content. Turn it on in tests. See Strict mode.

Word

KeyDefaultDescription
docx.toc_page_numberstrueLays 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_convertenv('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

KeyDefaultDescription
html.fonts'none''none', 'embed', 'link' or 'sources'. See Fonts in HTML.
html.font_urlnullA FontUrlResolver class. Required when fonts is 'link'.
html.image_urlnullAn ImageUrlResolver class. null embeds images as data URIs.
html.inline_svgsfalsetrue 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.familiesnullnull for every family, or a list of the families to load.
html.local_fonts.mode'embed''embed' or 'link'.
html.local_fonts.familiesnullnull 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

KeyDefaultDescription
markup.imagesnullAn 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.toctruefalse keeps the headings markup converts out of tables of contents. See Rich text.
markup.highlighttruefalse 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.

KeyDefaultDescription
code.themenullThe default theme. null is quoin-light. A name from Phiki's bundled themes or code.themes.
code.variantnullnull, '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

KeyDefaultDescription
preview.enabledenv('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.

Edit this page on GitHub
Last Updated: 11/17/26, 2:47 PM
Prev
Laravel
Next
Preview routes