NextPDF Laravel integration

At a glance

This how-to sets up NextPDF in a Laravel 12 application. You complete six stages: install the package, let Laravel auto-discover it, publish the config, resolve the container bindings, return a Hypertext Transfer Protocol (HTTP) response, and run a queued job. Each stage links to the detailed reference for that area.

Install

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Boot/auto-discovery

Laravel auto-discovers the service provider and facade alias from the package composer.jsonextra.laravel block. You do not need to edit config/app.php. The autoload map uses one PSR-4 entry. The NextPDF\Laravel\ prefix resolves to src/Laravel/ under the PSR-4 prefix-to-base-directory rule (PSR-4 §3). Because the provider is deferred, it boots only when one of its provides() entries is first resolved. For full discovery internals, see /integrations/laravel/boot-and-discovery/.

Container bindings

Resolve the document contract from the container. A bound identifier resolves to its registered entry (PSR-11 §1.1.2). The document binding is a factory, so each resolve returns a fresh document. The font and image registries are singletons, so each resolve returns the same shared instance. For the full binding-lifetime table, see /integrations/laravel/overview/ and /integrations/laravel/boot-and-discovery/.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Wired through the container', newLine: true);

Publish config

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

This command writes config/nextpdf.php. The configuration reference covers every key, its environment variable, and its default in /integrations/laravel/configuration/.

Service-provider/bundle smoke test

The package includes a Testbench-based test suite that exercises the provider end to end. Add this minimal smoke test to a consuming application:

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

These two assertions mirror the package’s use-once conformance checks in EInvoiceServiceProviderIntegrationTest. They confirm that the document is factory-bound and that the font registry is a locked singleton.

Public API entry points

Entry point	Purpose	Reference
`NextPDF\Laravel\Facades\Pdf`	Static proxy to a fresh document	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Container-resolved document	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Inline, download, and streamed HTTP responses	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Queued generation	/integrations/laravel/production-usage/

Code sample — Production

The full controller shows dependency injection and error handling in /integrations/laravel/production-usage/. The same page covers the queued job and its success and failure callbacks.

Edge cases & gotchas

Resolve PdfDocumentInterface, not the concrete Document, so the binding stays testable and swappable.
SignerInterface and TsaClient resolve to null until configured. Always check for null.
The e-invoice contracts require nextpdf/premium. They are bound but error on first resolve without it.

Performance

End-to-end wiring adds no boot cost because the provider is deferred. First-resolve construction costs and font warmup costs are covered in /integrations/laravel/boot-and-discovery/.

Security notes

PdfResponse applies a fixed Open Worldwide Application Security Project (OWASP) header set. GeneratePdfJob validates its output path on the worker. See /integrations/laravel/security-and-operations/ for the threat model.

Conformance

Claim	Source	Clause	reference_id
Bound identifier resolves to its registered entry	PSR-11 Container	§1.1.2
PSR-4 prefix maps to base directory	PSR-4 Autoloader	§3

Commercial context

When nextpdf/premium is installed, signing, PDF/A, and e-invoice contracts integrate through the same provider. The Core package documented here needs no code change to adopt this optional Enterprise capability. See https://nextpdf.dev/get-license/?intent=laravel-signing.