Asset Pipeline

BladePDF resolves images, stylesheets, fonts, and other files referenced by your documents. Local Laravel renders can attach files automatically, while cloud templates can use assets managed in the dashboard and override them for a single request.

Local HTML assets

When you call fromView(), the package first renders your Laravel view to HTML, scans it for local file references, uploads those files with the render request, and rewrites references to asset:///... URLs.

 1<link rel="stylesheet" href="{{ asset('css/invoice.css') }}">
 2<img src="{{ asset('images/logo.png') }}" alt="Logo">

The package can resolve local paths from your public directory, relative CSS references, absolute filesystem paths, and local hosts configured through APP_URL.

Scanned references

External URLs

External http:// and https:// URLs are preserved. Availability depends on your plan and network settings. Unsafe destinations and unsupported protocols are blocked.

Disable automatic resolution

Automatic asset resolution is enabled by default. If you want BladePDF to leave your HTML and CSS references untouched, disable it globally with an environment variable:

 1BLADEPDF_AUTO_RESOLVE_ASSETS=false

Or disable it for one render:

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

Manual assets added with withAsset() or overrideAsset() are still uploaded. Only the automatic scan-and-rewrite step is skipped. If you prefer a toggle-style call, resolveAssets(false) is equivalent to withoutAssetResolution().

Manual assets

Use withAsset() when your HTML already references an asset:///... URL or when you want full control over the request asset name.

 1$html = '<;img src="asset:///brand-logo.png">';
 2
 3return BladePDF::fromHtml($html)
 4    ->withAsset(public_path('images/logo.png'), 'brand-logo.png', 'image/png')
 5    ->render()
 6    ->response();

Cloud template assets

Cloud templates can reference dashboard assets using the asset:/// scheme. If a request provides an override with the same asset name, the uploaded file is used for that render only.

 1<img src="asset:///bladepdf-old-logo-colored.png" alt="Logo">
 2<link rel="stylesheet" href="asset:///invoice.css">

Per-request overrides

Use overrideAsset() to replace a cloud asset for one render request. This is useful for tenant logos, one-off attachments, and generated images.

 1return BladePDF::fromTemplate('invoice.standard', $context)
 2    ->overrideAsset('bladepdf-old-logo-colored.png', public_path('tenant-logo.png'))
 3    ->render()
 4    ->response();

Asset metrics

Render details include asset timing and counts:

• assets_resolve_ms
• assets_resolved_count
• assets_cache_hits
• assets_uploaded_count

These metrics appear in the dashboard render detail and help explain how assets affected a render.

Troubleshooting