README

Official Laravel package for the BladePDF PDF generation API.

Installation

composer require bladepdf/laravel

Publish config:

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

Set your API Key:

BLADEPDF_API_KEY=your_api_key

Basic usage

use BladePDF\Laravel\Facades\BladePDF;

return BladePDF::fromView('pdf.invoice', [
    'invoice' => $invoice,
])
    ->withHeader('pdf.header')
    ->withFooter('pdf.footer')
    ->templateName('Invoice')
    ->reference($invoice->uuid)
    ->format('A4')
    ->margins(80, 20, 60, 20)
    ->showBackground()
    ->waitUntil('networkidle0')
    ->emulateMedia('screen')
    ->render()
    ->response('invoice.pdf');

Cloud templates

Render a template that is stored in BladePDF cloud storage by sending its template id and the JSON context used by the remote Blade renderer:

return BladePDF::fromTemplate('invoice.standard', [
    'invoice' => $invoice,
    'customer' => $invoice->customer,
])
    ->reference($invoice->uuid)
    ->storePdf()
    ->format('A4')
    ->showBackground()
    ->render()
    ->response('invoice.pdf');

Cloud template renders send source={"type":"template","templateId":"..."} and a multipart context.json file. Header and footer HTML overrides are not supported for cloud templates because they are part of the stored template configuration.

Supported multipart form fields

All fields are optional and are sent as multipart/form-data to POST https://api.bladepdf.com/render:

• source (JSON encoded)
• metadata (JSON encoded)
• store_pdf
• webhook (JSON encoded)
• wait_until
• wait_function
• emulate_media
• html
• header_html
• footer_html
• context
• pdf_options (JSON encoded)

HTML renders send source={"type":"html"} and upload html.html. Cloud template renders send source={"type":"template","templateId":"..."} and upload context.json.

Metadata and stored PDFs

Use a reference to correlate a render with your own model:

BladePDF::fromTemplate('invoice.standard', $context)
    ->reference($invoice->uuid)
    ->storePdf()
    ->render();

For raw HTML or local Blade view renders, you may also provide a dashboard display name:

BladePDF::fromView('pdf.invoice', ['invoice' => $invoice])
    ->templateName('Tenant invoice')
    ->reference($invoice->uuid)
    ->render()
    ->pdf();

templateName() is only accepted for HTML renders. Cloud template renders already identify the stored template through templateId.

Per-request webhooks

Use webhook() when a single asynchronous render should notify a specific endpoint in addition to any dashboard-configured webhooks:

BladePDF::fromTemplate('invoice.standard', $context)
    ->reference($invoice->uuid)
    ->storePdf()
    ->webhook('https://example.com/bladepdf/webhook', 'whsec_request_secret')
    ->async();

The optional third argument limits which events are delivered:

BladePDF::fromHtml($html)
    ->storePdf()
    ->webhook('https://example.com/bladepdf/webhook', 'whsec_request_secret', ['pdf.rendered'])
    ->async();

Asynchronous renders

Submit a render without waiting for the generated PDF. The request still waits for validation, quota admission, and input staging. Rendering then continues in the background and delivers its result through the configured webhook:

$submission = BladePDF::fromTemplate('invoice.standard', $context)
    ->reference($invoice->uuid)
    ->storePdf()
    ->webhook(route('webhooks.bladepdf'), config('services.bladepdf.webhook_secret'))
    ->async();

$submission->requestId;
$submission->reference;

storePdf() is required for every asynchronous render. The API returns 202 Accepted only after the render has been accepted for background processing. Validation, storage quota, upload, and capacity failures are still thrown synchronously.

PDF options

Common PDF options are available as fluent methods:

BladePDF::fromHtml('<h1>Hello</h1>')
    ->format('A4')
    ->landscape()
    ->margins(10, 10, 15, 10)
    ->showBackground()
    ->scale(0.9)
    ->pages('1-3')
    ->taggedPdf()
    ->preferCssPageSize()
    ->waitForFonts()
    ->outline()
    ->render()
    ->pdf();

You can still pass raw options when you need lower-level control:

BladePDF::fromHtml('<h1>Hello</h1>')
    ->withOptions(['printBackground' => true])
    ->render()
    ->pdf();

Asset pipeline

When the package renders your Blade templates, it automatically scans the HTML and CSS for local assets and uploads them as multipart fields using the asset:///... scheme.

It rewrites these asset references automatically:

• src, href, poster, data-src, data-href
• srcset
• inline style="..."
• <style>...</style> blocks
• CSS url(...)
• CSS @import

Examples of local references that can be rewritten:

• /images/logo.png
• {{ asset('css/app.css') }} when it resolves to your local app host
• relative CSS references like ../fonts/inter.woff2
• absolute filesystem paths

External URLs such as CDN files are preserved as-is.

Automatic asset resolution is enabled by default. You can disable it globally when you want BladePDF to leave your HTML untouched:

BLADEPDF_AUTO_RESOLVE_ASSETS=false

You can also disable it for a single render:

return BladePDF::fromView('pdf.invoice', ['invoice' => $invoice])
    ->withoutAssetResolution()
    ->render()
    ->response();

Manual assets added with withAsset() or overrideAsset() are still uploaded when automatic resolution is disabled. If you prefer a toggle-style call, resolveAssets(false) is equivalent to withoutAssetResolution().

Manual assets

If you want to upload an asset yourself and reference it manually inside custom HTML, you can attach it explicitly:

$html = '<html><body><img src="asset:///brand-logo.png"></body></html>';

return BladePDF::fromHtml($html)
    ->withAsset(public_path('images/logo.png'), 'brand-logo.png')
    ->render()
    ->response();

For cloud templates, use overrideAsset() to replace a stored asset:///... reference for a single render request:

return BladePDF::fromTemplate('invoice.standard', $context)
    ->overrideAsset('brand-logo.png', public_path('images/tenant-logo.png'))
    ->render()
    ->response();

Request asset override targets must be simple file names containing only letters, numbers, dots, underscores, and hyphens.

Raw HTML usage

return BladePDF::fromHtml('<h1>Hello world</h1>')
    ->format('A4')
    ->render()
    ->response();

Saving to disk

BladePDF::fromView('pdf.report')
    ->render()
    ->save(storage_path('app/report.pdf'));

Base64 output

$base64 = BladePDF::fromTemplate('invoice.standard', $context)
    ->render()
    ->base64Pdf();

Suggested facade alias

use BladePDF\Laravel\Facades\BladePDF;

Development

composer install
composer lint
composer test

License

This package is open-sourced software licensed under the MIT license.