Laravel
quoin/laravel lets you write documents as Blade views. Each <x-doc::*> tag builds a core component, and the whole view becomes one document. Loops, conditionals, slots and your own components work as in any other Blade view.
See Installation to add the package. Laravel discovers the service provider and the Quoin facade automatically.
A view and a route
{{-- 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'));| Call | What you get back |
|---|---|
Quoin::view($view, $data) | a PendingDocument |
->pdf() | a PendingOutput: download(), streamDownload(), inline(), save(), store(), toString(), output(), attachment() (see Attaching to mail) |
->html() | a PendingHtml; see HTML export |
->docx() | a PendingOutput for a Word file. Needs quoin/docx, or it throws MissingExporter; see Word export |
->theme($values) | a copy with a theme override; see Theme per document or page |
->encrypt($password) | a copy whose PDF needs a password; see Passwords |
->document() | the core Document the view built |
Quoin::make($document) | a PendingDocument for a document built in PHP |
Attaching to mail
A PendingOutput goes straight into a mailable or notification. The document renders once, when attached. The attachment is named document.pdf, document.docx or document.html with the right MIME type. In a mailable, build it in attachments() from data the mailable can serialize:
public function attachments(): array
{
return [Quoin::view('pdf.invoice', ['invoice' => $this->invoice])->pdf()];
}In a notification, attach it in toMail():
return (new MailMessage)
->subject('Your invoice')
->attach(Quoin::view('pdf.invoice', ['invoice' => $invoice])->pdf());Build the document inside attachments() or toMail(), and don't store a PendingOutput on a queued mailable: it holds a closure, which can't be serialized.
attachment() takes a name of your own, cleaned the way download() cleans it, and returns an Illuminate\Mail\Attachment you can chain on. Naming it does not render the document.
return [Quoin::view('pdf.invoice', ['invoice' => $this->invoice])->pdf()->attachment('invoice-142.pdf')];->html() attaches the full page.
Macros
QuoinManager, PendingDocument, PendingOutput and PendingHtml use Laravel's Macroable, so you can add shortcuts of your own. Inside the closure, $this is the object:
use Quoin\Laravel\PendingOutput;
PendingOutput::macro('toArchive', fn (string $path) => $this->store($path, 'archive'));
Quoin::view('pdf.invoice', $data)->pdf()->toArchive('invoices/142.pdf');Your own components
Your own Blade components can wrap <x-doc::*> tags. Keep pieces shared across documents there, such as a branded header or a stat card.
{{-- resources/views/components/stat-card.blade.php --}}
@props(['label', 'value', 'color' => 'slate-900'])
<x-doc::column gap="3pt" padding="14pt" background="slate-50" radius="8pt" grow="1">
<x-doc::text size="8pt" bold color="slate-500">{{ $label }}</x-doc::text>
<x-doc::text size="22pt" bold :color="$color">{{ $value }}</x-doc::text>
</x-doc::column><x-doc::row gap="8pt">
<x-stat-card label="SECTIONS" value="4" color="indigo-600" />
<x-stat-card label="TABLE ROWS" :value="count($rows)" color="emerald-600" />
</x-doc::row>Build on the decorators where you can. A question component made from section, field and choices picks up the theme and matches your other documents.
Passing values
Attributes accept plain strings (gap="8pt") or PHP values with the usual colon syntax (:gap="$gap"). Boolean attributes can be written on their own (bold) or bound to a value (:bold="$isTotal").
Embedding PHP-built nodes
<x-doc::node :node="$node" /> places a component built in PHP inside a Blade view. Use it for a chart, a table assembled in a service class, or anything easier to build in code.
Inside a text tag, a Text node becomes part of the line. An inline tag like <b> can't wrap an embedded node, so close it on either side:
<x-doc::text><b>x </b><x-doc::node :node="$t" /><b> y</b></x-doc::text>Theme per document or page
Change the theme for one document with :theme on <x-doc::document>, for one page with :theme on <x-doc::page>, or from a controller with ->theme():
<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();The keys are font_family, mono_family, font_size, color, line_height, code_theme and styles (in the shape of quoin.styles); the first five work as in quoin.theme. A font family must be bundled or registered in fonts (see Fonts); Merriweather above is an example. The order is config, the view's document, the controller's ->theme(), then the page. A theme override on a page also reaches content passed through a layout or wrapper component's slot.
Named styles in an override merge onto the existing style. Blade checks style names while it renders the view, before the controller's ->theme() runs. So ->theme() can change values and restyle existing names, but a new style name the view uses must be defined in quoin.styles or in a :theme in the view. See Changing the theme for one document or page.
Caching
Cache data, not rendered <x-doc> output. A rendered fragment holds markers that only mean something inside the render that made it, so a fragment kept in a cache, a static property or once() and then placed in a later render can't be used. It stops with an InvalidStructure error that says it found a node marker from another render. Cache the data behind the fragment and render the fragment each time.
This isn't always detected. Only markers made earlier in the same process are recognized; a fragment cached across workers, or kept long after, can instead show up as literal marker text ([[pc:…]]) in the output, or as a "can only contain" error whose message adds a note about the marker.
The tag prefix
Tags use the doc prefix by default. If it clashes with something in your app, change prefix in the configuration.
When something goes wrong
If a tag has an attribute it doesn't recognize, the render stops with an UnknownAttribute error that names the tag and suggests what you probably meant:
Unknown attribute "colour" on <x-doc::text>. Did you mean "color"?Tags in the wrong place, such as an <x-doc::tr> outside a table or a view without an <x-doc::document> root, throw InvalidStructure.
Laravel wraps any exception thrown while rendering a view in an Illuminate\View\ViewException. getPrevious() returns the original exception.