Referência da API para Laravel

Visão geral

O pacote nextpdf/laravel conecta o núcleo independente de framework do NextPDF a uma aplicação Laravel. Você chama diretamente quatro pontos de entrada: a facade Pdf para fluxos curtos de criação, o binding do container PdfDocumentInterface para criar documentos por injeção de dependência, o auxiliar PdfResponse para respostas HTTP com documentos concluídos e o job de fila GeneratePdfJob para geração fora da requisição. O NextPdfServiceProvider registra cada binding e é descoberto automaticamente; portanto, você não precisa fazer configuração manual. A configuração em config/nextpdf.php controla os padrões, as fontes, as filas e os recursos opcionais de assinatura e de autoridade de carimbo de tempo (TSA).

Comece por aqui: para enviar um arquivo Portable Document Format (PDF) diretamente de um controller, crie um documento e retorne PdfResponse::download($document, 'file.pdf'). O primeiro exemplo abaixo mostra esse fluxo.

Tarefas comuns

Os trechos de código abaixo cobrem os três fluxos que você costuma usar primeiro. Cada trecho é conferido com o código-fonte do pacote; as tabelas completas por símbolo vêm em seguida.

Retorne um PDF para download a partir de um controller. Esta é a tarefa mais comum:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

O que faz: injeta um documento novo, escreve uma linha e retorna uma resposta attachment com Content-Type: application/pdf e os cabeçalhos de segurança do Open Worldwide Application Security Project (OWASP). Use inline() no lugar de download() para visualizar no navegador.

Crie e salve com a facade Pdf. Este é o caminho mais direto para scripts e fluxos curtos:

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

O que faz: a facade resolve um documento novo a partir do container, escreve uma célula e salva no disco o PDF concluído.

Gere um PDF fora da thread da requisição com GeneratePdfJob:

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

O que faz: enfileira a geração em um worker. A closure builder recebe um documento resolvido pelo container e o retorna. O job valida o caminho de saída .pdf antes de salvar. O nome da fila, o timeout e a conexão são obtidos de config('nextpdf.queue.*').

Facade

A facade Pdf faz proxy estático de um Document novo do núcleo. Use-a em fluxos curtos de controller quando o estilo estático deixar a intenção clara. Cada linha lista um método de documento exposto por proxy.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
`NextPDF\Laravel\Facades\Pdf`	nenhum; o accessor estático da facade resolve `NextPDF\Contracts\PdfDocumentInterface`	O Laravel resolve o binding atual do container para a interface de documento.	A API fluente do documento do núcleo subjacente.	Falha no binding do container do Laravel se o provider não estiver registrado.	Use-a para fluxos curtos de controller. Prefira injeção via construtor para serviços e jobs.
`Pdf::setTitle(string $title)`	`title`: título do documento.	Substitui qualquer título existente.	`static`	Erros de validação do núcleo ou de gravação.	Faz proxy para o `Document` do núcleo.
`Pdf::setAuthor(string $author)`	`author`: metadados de autor do documento.	Substitui qualquer autor anterior.	`static`	Erros de validação de metadados do núcleo.	Prefira os padrões configurados para metadados válidos em toda a aplicação.
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`: tamanho de página opcional; `orientation`: `Portrait` por padrão.	Usa o tamanho de página configurado ou padrão quando `size` é omitido.	`static`	Erros de validação de página do núcleo.	Use um `PageSize` explícito quando o tamanho da saída for importante.
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	Família da fonte, estilo e tamanho em pontos.	Usa estilo vazio e tamanho de 12 pt.	`static`	Erros de registro de fontes ou de codificação.	Pré-carregue as fontes de produção por meio de `nextpdf.preload_fonts` quando a latência for importante.
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	Caixa da célula, texto, flag de borda, flag de quebra de linha e alinhamento.	Usa texto vazio, sem borda, sem quebra de linha e alinhamento à esquerda.	`static`	Erros de layout ou de codificação de texto.	Use para saídas simples com layout fixo.
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	Largura da célula, altura da linha, texto, flag de borda e alinhamento.	Sem borda e alinhamento à esquerda.	`static`	Erros de layout ou de codificação de texto.	Use quando o texto precisar quebrar dentro de uma largura fixa.
`Pdf::writeHtml(string $html)`	`html`: fragmento de HTML.	Renderiza na página atual e cria uma página quando necessário.	`static`	Erros de renderização de HTML do núcleo.	Aplique políticas de tamanho de entrada e de recursos antes de aceitar HTML não confiável.
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	Caminho do arquivo e retângulo de posicionamento opcional.	Permite que o documento do núcleo escolha a posição atual e o tamanho intrínseco quando as coordenadas são omitidas.	`static`	Erros de decodificação de imagem, de caminho ou de layout.	Valide a política de origem de imagens antes de aceitar caminhos fornecidos pelo usuário.
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`: nome opcional; `dest`: destino de saída.	Emite a saída inline quando o destino é omitido.	`string`	Erros de serialização do núcleo.	Prefira `PdfResponse` para respostas HTTP no Laravel.
`Pdf::save(string $path)`	`path`: destino no sistema de arquivos.	Grava o PDF concluído no disco.	`void`	Erros de sistema de arquivos ou de gravação do núcleo.	Valide os diretórios de saída no código da aplicação.
`Pdf::getPdfData()`	nenhum.	Materializa os bytes do PDF na memória.	`string`	Erros de serialização do núcleo.	Use quando outro objeto do framework precisar assumir o corpo da resposta.

Service provider e bindings

Use esta tabela quando precisar resolver ou sobrescrever diretamente uma entrada de container, como ao injetar DocumentFactoryInterface em um serviço ou ao verificar o que provides() adia.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
`NextPdfServiceProvider::register()`	nenhum.	Mescla `config/nextpdf.php`; registra os registries, a document factory, o binding de documento, o cliente HTTP, o cliente TSA, o signer e os contratos opcionais de e-invoice.	`void`	Erros de resolução de container ou de classes opcionais quando um recurso é usado.	`FontRegistryInterface` e `ImageRegistry` são compartilhados; os documentos são sempre novos.
`NextPdfServiceProvider::boot()`	nenhum.	Valida as extensões PHP obrigatórias e publica `nextpdf-config` em modo console.	`void`	`RuntimeException` se uma extensão obrigatória estiver indisponível.	As extensões obrigatórias são `mbstring` e `zlib`.
`NextPdfServiceProvider::provides()`	nenhum.	Informa os IDs dos serviços diferidos.	`array<string>`	nenhum esperado.	Inclui `PdfDocumentInterface`, `DocumentFactoryInterface`, `FontRegistryInterface`, `SignerInterface`, `TsaClient`, `ClientInterface` e `nextpdf`.
`PdfDocumentInterface` / `nextpdf`	resolvido a partir do container do Laravel.	Cria um `Document` descartável por meio de `DocumentFactoryInterface` e, em seguida, aplica os padrões configurados e as configurações opcionais de PDF/A ou Artisan.	`NextPDF\Core\Document`	Erros de extensão opcional quando configurada, mas indisponível.	Resolva um documento novo para cada requisição ou job.
`DocumentFactoryInterface`	resolvido a partir do container do Laravel.	Factory singleton que compartilha os registries de fontes e de imagens durante o tempo de vida do processo.	`DocumentFactoryInterface`	Erros de configuração de registry.	Use isto para injeção de dependência explícita.
`SignerInterface`	resolvido a partir do container do Laravel.	Retorna `null` a menos que `nextpdf.signature.enabled` esteja definido e os caminhos de certificado estejam configurados.	`SignerInterface	null`	Erros de carregamento de certificado ou de validação de nível de assinatura.

Configuração

Use esta tabela para consultar as chaves nextpdf.* voltadas ao runtime que são lidas pelos bindings. A referência completa por chave, incluindo variáveis de ambiente e padrões, está em /integrations/laravel/configuration/.

Chave	Tipo	Comportamento padrão	Observações
`nextpdf.fonts_path`	`string`	Usa as fontes de recursos do Laravel quando omitido.	Diretório para fontes personalizadas e aquecimento.
`nextpdf.cache_path`	`string`	Caminho de cache da aplicação.	Mantenha-o gravável pelo worker PHP.
`nextpdf.preload_fonts`	`list<string>`	Lista vazia.	Aquecida durante a criação do registry; depois, o registry é bloqueado.
`nextpdf.image_cache_mb`	`int`	Tamanho de cache de imagens limitado.	Limita a memória do cache de imagens durante o tempo de vida do processo.
`nextpdf.defaults.*`	`array`	Criador `NextPDF`, idioma `en`, padrões opcionais de autor e de layout.	Aplicados a cada documento novo.
`nextpdf.artisan.*`	`array`	O renderizador Chrome fica desativado, a menos que esteja instalado e configurado.	Mapeia para `ChromeRendererConfig::fromArray()`.
`nextpdf.signature.*`	`array`	Assinatura desativada por padrão.	Certificado, chave privada, senha, certificados extras e nível de assinatura.
`nextpdf.tsa.*`	`array`	TSA desativada quando o Uniform Resource Locator (URL) está vazio.	Suporta credenciais, arquivos de mutual Transport Layer Security (mTLS), timeout, pins de chave pública e política de HTTP.
`nextpdf.ocsp_cache.*`	`array`	Cache do Online Certificate Status Protocol (OCSP) ativado com o TTL configurado.	Usado pelos fluxos de validação de assinatura quando disponível.

Respostas HTTP

Use esta tabela quando você retornar um documento concluído por HTTP e precisar escolher entre exibição inline, download como anexo ou saída via streaming.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: documento construído; `filename`: nome de arquivo do Content-Disposition.	Normaliza nomes de arquivo vazios para `document.pdf`.	`Illuminate\Http\Response`	Erros de serialização do núcleo ou de construção da resposta.	Define o content type de PDF e cabeçalhos defensivos.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	O mesmo que `inline`; a disposition é attachment.	Retorna uma resposta de download do navegador.	`Illuminate\Http\Response`	O mesmo que `inline`.	Use para downloads de arquivo explícitos.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	O mesmo que `inline`.	Materializa os bytes do PDF e, em seguida, emite chunks de 64 KB.	`Symfony\Component\HttpFoundation\StreamedResponse`	O mesmo que `inline`.	Isto é saída HTTP via streaming, não renderização zero-copy.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	O mesmo que `streamInline`; a disposition é attachment.	Resposta de stream de download.	`StreamedResponse`	O mesmo que `streamInline`.	Imponha limites de tamanho de entrada e de saída antes de renderizar.

Job de fila

Use esta tabela quando você mover a geração para fora da thread da requisição. Ela cobre a construção, o dispatch e os callbacks de sucesso ou falha de GeneratePdfJob.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`: `.pdf` de destino; `builder`: recebe um `PdfDocumentInterface`; os callbacks são opcionais.	O nome da fila, o timeout e a conexão são lidos de `config('nextpdf.queue.*')`.	Instância do job.	Erros de serialização se o builder ou os callbacks não puderem ser serializados.	O builder deve retornar o documento configurado.
`GeneratePdfJob::handle()`	nenhum.	Resolve `PdfDocumentInterface`, aplica o builder, valida o caminho de saída e, em seguida, salva.	`void`	`InvalidArgumentException` para caminhos de saída inseguros; erros de gravação do núcleo.	Rejeita stream wrappers, bytes nulos, segmentos `..` e caminhos que não sejam `.pdf`.
`GeneratePdfJob::failed(Throwable $exception)`	`exception`: causa da falha.	Chama o callback de falha configurado quando presente.	`void`	Falhas de callback.	Mantenha os callbacks idempotentes.
`GeneratePdfJob::then(callable $callback)`	`callback`: recebe o caminho de saída.	Substitui o callback de sucesso.	`self`	Erros de closure serializável.	Auxiliar fluente para a configuração do dispatch.
`GeneratePdfJob::catch(callable $callback)`	`callback`: recebe o `Throwable` lançado.	Substitui o callback de falha.	`self`	Erros de closure serializável.	Use para alertas ou limpeza compensatória.

Notas de desenvolvimento

PdfResponse sempre chama getPdfData() antes de construir uma resposta. Ele não é um construtor preguiçoso de documentos.
Os payloads de fila podem ser adulterados em transportes compartilhados; mantenha os caminhos de saída confinados a um diretório pertencente à aplicação.
Use um documento novo por requisição ou job. Não reutilize um documento entre requisições.