NextPDF Laravel: guia rápido

Visão geral

Neste tutorial, você cria um arquivo Portable Document Format (PDF) para download usando um controller. Depois, move o mesmo trabalho para um job enfileirado. Cada trecho de código corresponde ao comportamento verificado pela suíte de testes do pacote.

Instalação

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

Visão conceitual

Três pontos de entrada cobrem quase todos os casos de uso do Laravel. A facade é a forma mais rápida de começar. PdfResponse transforma um documento em uma resposta Hypertext Transfer Protocol (HTTP). Um job enfileirado remove a geração pesada da thread da requisição, para que você não precise esperar por ela. Este tutorial percorre cada ponto de entrada, um por vez. As versões prontas para produção adicionam tratamento de erros e estão em /integrations/laravel/production-usage/.

Exemplo de código — guia rápido

1. Facade

A cada chamada, a facade resolve um novo documento a partir do container. O container é o registro de serviços do Laravel. Este trecho de código corresponde ao comportamento verificado por tests/Unit/Laravel/Facades/PdfTest.php.

<?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'));

2. Resposta de download a partir de um controller

PdfResponse::download() retorna um Illuminate\Http\Response com Content-Type: application/pdf, disposição como attachment e cabeçalhos de segurança do Open Worldwide Application Security Project (OWASP). tests/Unit/Laravel/Http/PdfResponseTest.php verifica o código de status, o content type, o prefixo dessa disposição e os cabeçalhos.

<?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(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

Para exibir uma pré-visualização inline no navegador, troque download() por inline(). Para documentos grandes, use streamInline() ou streamDownload(). Esses métodos enviam o PDF em blocos determinísticos de 64 KB.

3. Geração enfileirada

GeneratePdfJob cria e salva um PDF em um worker da fila. A closure de construção recebe o documento resolvido a partir do container e retorna o documento configurado. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php confirma que o job cria o arquivo no caminho exato de saída.

<?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 caminho de saída deve terminar em .pdf. O job valida o caminho no worker antes de gravar.

Exemplo de código — produção

As versões de produção adicionam tratamento explícito de erros, callbacks de sucesso e de falha no job e uma estratégia de exceções tipadas. Elas estão documentadas por completo em /integrations/laravel/production-usage/.

Casos de borda e pegadinhas

A cada resolução, a facade retorna uma instância de documento diferente. Não armazene em cache Pdf::getFacadeRoot() entre documentos lógicos.
Se você passar um nome de arquivo vazio para qualquer factory de PdfResponse, ela usa o padrão document.pdf. A suíte de testes de resposta verifica esse padrão.
Nomes de arquivo não ASCII recebem automaticamente um parâmetro RFC 5987 filename*=. Nomes ASCII não recebem.
GeneratePdfJob rejeita path traversal, stream wrappers, bytes nulos e qualquer extensão diferente de .pdf. Ele lança InvalidArgumentException no worker.

Desempenho

Um documento de página única é gerado com folga dentro do orçamento de tempo por página listado no front matter. Mover a geração para GeneratePdfJob remove totalmente da requisição HTTP o tempo de construção do PDF. A requisição retorna assim que o job é despachado.

Notas de segurança

PdfResponse oferece factories que aplicam um conjunto fixo de cabeçalhos OWASP. Elas também sanitizam o nome do arquivo de download. O job enfileirado valida o próprio caminho de saída. A cobertura detalhada de ameaças está disponível em /integrations/laravel/security-and-operations/.

Conformidade

Nenhum padrão normativo rege este tutorial. Cada trecho de código é verificado em relação ao código-fonte do pacote e ao teste correspondente em tests/.

Contexto comercial

A saída assinada e em PDF/A está disponível com nextpdf/premium como um recurso Enterprise opcional. O pacote Core documentado aqui não exige nenhuma alteração de código para adotar esse recurso. Consulte https://nextpdf.dev/get-license/?intent=laravel-signing.

Veja também

/integrations/laravel/install/ — instalar e publicar a configuração
/integrations/laravel/production-usage/ — controller e job conectados com injeção de dependência e tratamento de erros
/integrations/laravel/configuration/ — chaves de configuração usadas aqui
/integrations/laravel/overview/ — arquitetura e ciclos de vida dos bindings