Download the PHP package kukux/pdf-template-builder without Composer

PDF Template Builder

Installation

1. Require the package

2. Publish and run the migrations

Upgrading from an earlier version? Re-publish and migrate — add_settings_to_pdf_templates_table adds the settings column that stores page margins. The builder degrades gracefully until you do: margins simply aren't persisted.

3. Publish assets

The builder UI is a React SPA bundled with Vite. The package ships pre-built JS in resources/dist/. Publish to public/:

Re-run this command after each package update to get the latest bundle.

This publishes two files: pdf-builder.js and pdf.worker.min.js, pdf.js's worker. Both must be served from your public/ — the canvas loads the worker same-origin so it always matches the bundled pdf.js API. If your host page also bundles pdf.js (a file previewer, say), a mismatched worker on globalThis would otherwise be picked up and every background render would fail with "API version … does not match the Worker version …".

The worker is published as .js although its contents are an ES module. pdf.js spawns it with { type: 'module' }, so the browser decides by Content-Type, and stock nginx has no mime.types entry for .mjs — it would serve application/octet-stream, which a module worker refuses.

For maintainers / contributors — to rebuild the bundle from JSX source:

ⓘ Filament v3 / v4 / v5 auto-detection

The plugin ships two parallel Resource implementations and aliases the canonical class name to the right one based on the Filament major version installed in your project.

Detection happens in PdfTemplateBuilderServiceProvider::register() via class_alias, before Filament's panel resolves any resource. You always reference the canonical Kukux\PdfTemplateBuilder\Filament\Resources\PdfTemplateResource::class — never the V3/V4 variants directly.

If you ever see Class "Kukux\…\PdfTemplateResource" not found after upgrading, run composer dump-autoload. PSR-4 lookup needs to miss so the alias can be consulted, and a stale optimized classmap can short-circuit that.

4. Register the plugin in your Filament panel

In your PanelProvider (e.g. app/Providers/Filament/AdminPanelProvider.php):

5. Register your models (optional but recommended)

Configure the Eloquent models whose fields will appear in the builder sidebar:

Alternatively, configure them in config/pdf-template-builder.php after publishing the config:

Descriptor keys

background is a URL the canvas loads behind the fields — typically a route in your app that renders the blank form the template stamps onto, so a designer never has to upload one by hand. It is used only when the template has no uploaded background of its own.

The token {used_in} in that URL is replaced with the template's used_in value, letting one descriptor serve several variants of the same document:

A template tagged used_in = "ics" then loads /forms/blank?type=ics. Serve a PDF or an image — the canvas renders PDFs with pdf.js.

Embedding the builder in your own page

The builder reads everything from window.__PDF_BUILDER__, so any Filament page can host it: render pdf-template-builder::pages.edit-pdf-template with your own $builderConfig. Beyond the keys the template editor passes, four make the canvas editable against something other than a template:

Enforce allowedKeys at your saveUrl too. It narrows the UI, not the request.

Your page renders its own header buttons; they reach the builder through DOM events — pdf-builder:save, pdf-builder:reset, pdf-builder:shortcuts and pdf-builder:preview. Skip Preview unless the record being edited really is a PdfTemplate, since it resolves the id against the template endpoint.

6. (Optional) Customize sidebar navigation

You can place the "PDF Templates" entry inside a Filament navigation group and control its sort order:

Or via the published config (config/pdf-template-builder.php):

Heads up — avoid this error

This is thrown when config('pdf-template-builder.navigation_group') resolves to null. To prevent it:

• If you published the config before v1.2.0, open config/pdf-template-builder.php and change 'navigation_group' => null to 'navigation_group' => '' (or to your preferred group name).
• Or set PDF_TEMPLATE_NAVIGATION_GROUP="" in your .env rather than leaving it unset.
• Or call ->navigationGroup('') explicitly when registering the plugin.

The same applies if you override the value at runtime — always pass a string, never null.

7. (Optional) Configure storage

By default PDF backgrounds are stored on the public disk under pdf-templates/backgrounds/. Override via the plugin or .env:

Or via the plugin:

What gets added to your app

• Navigation: A "PDF Templates" item in your Filament sidebar.
• Template list: Browse, search, and filter saved templates.
• Create form: Upload a background PDF, pick a model, set page size.
• Visual builder: Drag fields from the sidebar onto the PDF canvas, resize them, style their typography, and save the layout.
• API routes at /filament-pdf-builder/api/* (web + auth middleware).
• pdf_templates table in your database.

Using the builder

The page chrome — breadcrumbs, heading and the Shortcuts / Preview / Save template buttons — is rendered by Filament, so it inherits your panel's theme. Those buttons drive the React canvas through DOM events (pdf-builder:save, pdf-builder:preview, pdf-builder:shortcuts), which keeps the click client-side: the document being edited lives in the browser, so there is nothing for a Livewire round-trip to act on.

Canvas

Elements snap to each other, to the page edges and centre, and to the margin box. Toggle snapping, rulers, the grid and the margin guides from the canvas toolbar.

Pages

Add, duplicate, reorder and delete pages from the thumbnail rail, the canvas toolbar, the strip under each page, or the right-click menu. Deleting a page removes its elements and shifts later pages up; if the page isn't empty you're asked to confirm first, and ⌘Z undoes it either way.

Keyboard shortcuts

Press ? in the builder for the full list. The everyday ones:

On Windows and Linux, Ctrl replaces ⌘.

Generating PDFs

1. Install a PDF engine (optional but recommended)

The plugin auto-detects dompdf/dompdf and uses it for output. Without it, render() falls back to HTML (browser print → save as PDF still works).

2. Drop a "Generate PDF" button into any Filament page

On a ViewRecord / EditRecord page (header action):

As a row action on a Resource table:

Dynamic template selection:

3. Programmatic rendering

4. Field token resolution

Fields placed in the builder have a key like invoice.number or customer.email. At render time:

• The leading segment matching the template's model_key is stripped, then the remainder is resolved against the record via data_get().
• Otherwise the full key is resolved against the record (so relations work: customer.name → $invoice->customer->name).
• Pass extra named contexts via ->withContexts(['org' => $org]) and reference them with org.name in field tokens.

5. Choosing a PDF engine

The plugin ships three engines. Pick based on your needs:

Wire your choice on the plugin:

You can also implement Kukux\PdfTemplateBuilder\Rendering\Contracts\PdfEngine (or TemplateAwarePdfEngine for non-HTML pipelines like Browsershot) and register your own.

6. Running the test suite

The package ships with Pest tests covering routes, the field resolver, the HTML renderer, the filename pattern, and basic model persistence. Run them after every change.

7. Authorization

Templates use a default-permissive PdfTemplatePolicy. Override it in your AuthServiceProvider: