Cloud templates Template sources · 11 min read

Blade Templates

BladePDF can render local Laravel views, raw HTML strings, and templates managed in the BladePDF dashboard. Dashboard templates are useful when document design should be editable outside your application deploy cycle.

Render sources

Source	Use when	Entry point
Local view	The template lives in your Laravel app and can use your normal view data.	`fromView()`
Raw HTML	Your application already produced the final HTML string.	`fromHtml()`
Dashboard template	The template is created, edited, and published in BladePDF.	`fromTemplate()`

Local Laravel views

Use fromView() when Blade should run inside your Laravel application. The package renders the view locally, scans the resulting HTML for assets, uploads the render request, and returns the generated PDF.

Local view

php

 1return BladePDF::fromView('pdf.invoice', [
 2    'invoice' => $invoice,
 3])
 4    ->templateName('Invoice')
 5    ->reference($invoice->uuid)
 6    ->render()
 7    ->download('invoice.pdf');

Raw HTML

Use fromHtml() when you already have a complete HTML document.

Raw HTML

php

 1$html = '<html><body><h1>Hello</h1></body></html>';
 2
 3return BladePDF::fromHtml($html)
 4    ->format('A4')
 5    ->render()
 6    ->response();

Dashboard templates

Use fromTemplate() when the Blade source is managed in the dashboard. Your Laravel app sends the public template identifier plus JSON-friendly context data; BladePDF compiles the published template and renders the PDF.

Cloud template render

php

 1return BladePDF::fromTemplate('invoice.standard', [
 2    'invoice' => [
 3        'number' => $invoice->number,
 4        'issued_at' => $invoice->issued_at?->toDateString(),
 5        'total' => $invoice->total,
 6    ],
 7    'customer' => [
 8        'name' => $invoice->customer->name,
 9        'email' => $invoice->customer->email,
10    ],
11])
12    ->reference($invoice->uuid)
13    ->storePdf()
14    ->render()
15    ->response("invoice-{$invoice->number}.pdf");

Dashboard workflow

Create a template in the dashboard and choose a stable public identifier such as invoice.standard.
Edit the Blade source and template settings in the template editor.
Save drafts while working. Drafts do not affect API renders.
Publish the template when it is ready. API renders use the latest published version.
Render it from Laravel with fromTemplate('invoice.standard', $context).

Use template identifiers as API contracts

Choose identifiers that can stay stable over time, for example invoice.standard, shipping.label, or reports.monthly. The display name can change without changing the value your application uses.

Context data

Cloud templates receive a JSON object. Pass arrays, strings, numbers, booleans, and nulls. Convert Eloquent models and value objects before sending them so the template receives predictable data.

Context helpers

php

 1BladePDF::fromTemplate('invoice.standard')
 2    ->context([
 3        'invoice' => $invoice->toArray(),
 4    ])
 5    ->withContext([
 6        'locale' => app()->getLocale(),
 7        'generated_at' => now()->toIso8601String(),
 8    ])
 9    ->render()
10    ->pdf();

Inside the template, read the context like normal Blade data:

invoice.standard.blade.php

blade

 1<h1>Invoice {{ $invoice['number'] }}</h1>
 2<p>Customer: {{ $customer['name'] }}</p>
 3
 4@foreach ($invoice['items'] as $item)
 5    <div>{{ $item['description'] }} — {{ $item['amount'] }}</div>
 6@endforeach

Includes and layouts

Dashboard templates can use common Blade composition primitives such as @extends, @section, @yield, @include, and @each. Referenced templates are loaded from your published dashboard templates.

invoice.standard.blade.php

blade

 1@extends('layouts.invoice')
 2
 3@section('content')
 4    @include('partials.invoice-header')
 5
 6    <h1>Invoice {{ $invoice['number'] }}</h1>
 7@endsection

Header and footer templates for dashboard renders are selected in the template settings. They are not sent as per-request header_html or footer_html overrides.

Template settings

The template editor stores render settings with the published template. These settings become the default behavior whenever the template is rendered.

Setting	What it controls
Page format	A4, A5, Letter, Legal, or another supported paper size.
Orientation	Portrait or landscape.
Margins	Top, right, bottom, and left margins in millimeters.
Scale	PDF scale from `0.1` to `2.0`.
Print background	Whether CSS backgrounds and background images are printed.
Header and footer templates	Optional dashboard templates rendered as repeated page chrome.
Save rendered PDFs	Whether successful template renders should store the generated PDF in BladePDF by default.

You can still chain per-request PDF options from Laravel when you need a one-off override, for example ->landscape(), ->margins(...), or ->format('Letter'). Header and footer ownership stays with the published template settings.

Assets

Dashboard templates reference stored assets with asset:///.... Upload reusable logos, stylesheets, fonts, and images once in the dashboard, then reference them from any published template.

Dashboard template asset references

blade

 1<link rel="stylesheet" href="asset:///invoice.css">
 2<img src="asset:///brand-logo.png" alt="Brand logo">

Use overrideAsset() when one request should replace a stored asset without changing the published template. This is common for tenant logos or generated charts.

Request-scoped asset override

php

 1return BladePDF::fromTemplate('invoice.standard', $context)
 2    ->overrideAsset('brand-logo.png', public_path('tenants/acme/logo.png'), 'image/png')
 3    ->render()
 4    ->response('invoice.pdf');

Webhooks and render history

Template renders appear in render history with their template, reference, timing, asset metrics, and status. Dashboard webhook endpoints receive template render events the same way they receive local HTML render events.

Template render with a one-off webhook

php

 1$submission = BladePDF::fromTemplate('invoice.standard', $context)
 2    ->reference('INV-2026-0042')
 3    ->storePdf()
 4    ->webhook('https://example.com/bladepdf/webhook', 'whsec_request_secret', [
 5        'pdf.rendered',
 6    ])
 7    ->async();

See Webhooks for dashboard endpoints, per-request webhook delivery, signature verification, retries, and payload examples.

Metadata

reference() works for every render source and is the recommended way to attach your own invoice id, order number, or model uuid. templateName() is only for HTML renders, where there is no dashboard template identifier.

Metadata

php

 1BladePDF::fromView('pdf.invoice', $data)
 2    ->templateName('Custom invoice')
 3    ->reference('INV-2026-0042')
 4    ->render()
 5    ->pdf();
 6
 7BladePDF::fromTemplate('invoice.standard', $context)
 8    ->reference('INV-2026-0042')
 9    ->render()
10    ->pdf();

Supported cloud syntax

Dashboard templates support the Blade syntax commonly needed for documents:

Feature	Examples
Echoes	`{{ $invoice['number'] }}`, `{!! $trustedHtml !!}`
Conditionals	`@if`, `@elseif`, `@else`, `@unless`, `@isset`, `@empty`, `@switch`
Loops	`@foreach`, `@forelse`, `@for`, `@while`, `@break`, `@continue`
Includes	`@include`, `@includeIf`, `@includeWhen`, `@includeUnless`, `@includeFirst`, `@each`
Layouts	`@extends`, `@section`, `@yield`, `@parent`, `@show`, `@stack`, `@push`
Helpers	`@json`, `@js`, `@class`, `@style`

Unsupported cloud syntax

Dashboard templates intentionally do not execute arbitrary PHP. Avoid @php, raw PHP tags, service container access, auth/policy/session directives, Livewire, routing helpers, and Blade components or slots.