Integração do NextPDF com o Laravel

Visão geral

Este guia prático configura o NextPDF em uma aplicação Laravel 12. Você passa por seis etapas: instalar o pacote, permitir que o Laravel o descubra automaticamente, publicar a configuração, resolver os bindings do container, retornar uma resposta Hypertext Transfer Protocol (HTTP) e executar um job em fila. Cada etapa inclui um link para a referência detalhada da área correspondente.

Instalação

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

Inicialização/descoberta automática

O Laravel descobre automaticamente o service provider e o alias da facade a partir do bloco composer.jsonextra.laravel do pacote. Você não precisa editar config/app.php. O mapa de autoload usa uma única entrada PSR-4. O prefixo NextPDF\Laravel\ resolve para src/Laravel/ conforme a regra PSR-4 de mapeamento de prefixo para diretório-base (PSR-4 §3). Como o provider é deferido, ele só é inicializado quando uma de suas entradas provides() é resolvida pela primeira vez. Para ver todos os detalhes internos da descoberta, consulte /integrations/laravel/boot-and-discovery/.

Bindings do container

Resolva o contrato do documento pelo container. Um identificador vinculado resolve para a entrada registrada correspondente (PSR-11 §1.1.2). O binding do documento é uma factory; portanto, cada resolução retorna um documento novo. Os registries de fontes e imagens são singletons; portanto, cada resolução retorna a mesma instância compartilhada. Para ver a tabela completa de tempos de vida dos bindings, consulte /integrations/laravel/overview/ e /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);

Publicar a configuração

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

Este comando grava config/nextpdf.php. A referência de configuração cobre cada chave, a respectiva variável de ambiente e o valor padrão em /integrations/laravel/configuration/.

Smoke test do service-provider/bundle

O pacote inclui uma suíte de testes baseada em Testbench que exercita o provider de ponta a ponta. Adicione este smoke test mínimo em uma aplicação consumidora:

<?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());
    }
}

Essas duas assertions espelham as verificações de conformidade de uso único do pacote em EInvoiceServiceProviderIntegrationTest. Elas confirmam que o documento está vinculado como factory e que o registry de fontes é um singleton bloqueado.

Pontos de entrada da API pública

Ponto de entrada	Finalidade	Referência
`NextPDF\Laravel\Facades\Pdf`	Proxy estático para um novo documento	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Documento resolvido pelo container	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Respostas HTTP inline, para download e em streaming	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Geração em fila	/integrations/laravel/production-usage/

Exemplo de código — Produção

O controller completo mostra injeção de dependência e tratamento de erros em /integrations/laravel/production-usage/. A mesma página cobre o job em fila e seus callbacks de sucesso e falha.

Casos de borda e armadilhas

Resolva PdfDocumentInterface, não o Document concreto, para que o binding permaneça testável e substituível.
SignerInterface e TsaClient resolvem para null até serem configurados. Sempre verifique se o valor é null.
Os contratos de e-invoice exigem nextpdf/premium. Eles permanecem vinculados, mas geram erro na primeira resolução sem esse pacote.

Desempenho

A integração de ponta a ponta não adiciona custo de inicialização porque o provider é deferido. Os custos de construção na primeira resolução e os custos de aquecimento das fontes são abordados em /integrations/laravel/boot-and-discovery/.

Notas de segurança

PdfResponse aplica um conjunto fixo de cabeçalhos do Open Worldwide Application Security Project (OWASP). GeneratePdfJob valida o caminho de saída no worker. Consulte o modelo de ameaças em /integrations/laravel/security-and-operations/.

Conformidade

Afirmação	Fonte	Cláusula	reference_id
Identificador vinculado resolve para a entrada registrada correspondente	PSR-11 Container	§1.1.2
Prefixo PSR-4 mapeia para o diretório-base	PSR-4 Autoloader	§3

Contexto comercial

Quando o nextpdf/premium está instalado, os contratos de assinatura, PDF/A e e-invoice se integram por meio do mesmo provider. O pacote Core documentado aqui não precisa de nenhuma alteração de código para adotar esse recurso Enterprise opcional. Consulte https://nextpdf.dev/get-license/?intent=laravel-signing.

Veja também

/integrations/laravel/overview/ — arquitetura e tabela de bindings
/integrations/laravel/install/ — instalação e extensões opcionais
/integrations/laravel/quickstart/ — primeiro exemplo executável
/integrations/laravel/production-usage/ — injeção de dependência, tratamento de erros e fila
/integrations/laravel/boot-and-discovery/ — descoberta e tempos de vida