FAQ do NextPDF

Visão geral

Esta página responde às perguntas que surgem primeiro quando você avalia o NextPDF ou começa um novo projeto. Cada resposta é curta e leva à página que a cobre por completo. O NextPDF é um engine PHP 8.4 que gera e inspeciona documentos Portable Document Format (PDF) 2.0, o formato de arquivo definido pela ISO 32000-2.

Se você é totalmente novo, leia primeiro Comece a usar e depois volte aqui para os detalhes.

Primeiros passos

Qual edição eu preciso: Core, Pro ou Enterprise?

Comece com a Core. O núcleo open source (nextpdf/core) gera saída em PDF, renderiza HTML suportado em PDFs e inspeciona PDFs sob a licença Apache-2.0 e sem custo. A Core já produz assinaturas CMS SignedData para os níveis baseline B-B e B-T das PDF Advanced Electronic Signatures (PAdES). Escolha a Pro quando você precisar de geração avançada e operações de documentos, saída de fatura eletrônica (Factur-X / ZUGFeRD) ou fluxos de assinatura avançados, como assinatura remota, cloud-KMS e sequencial. Escolha a Enterprise quando você precisar de fluxos de autoria de arquivamento PDF/A, dos níveis de longo prazo PAdES (B-LT / B-LTA) com um Document Security Store e carimbos de tempo de documento, de assinatura apoiada em hardware por meio de um hardware security module (HSM) ou de assinaturas eletrônicas qualificadas. A Pro e a Enterprise são as duas edições licenciadas do NextPDF Premium, a linha paga; consulte Escolha seu caminho.

É realmente Apache-2.0?

Sim, para o núcleo. O nextpdf/core declara "license": "Apache-2.0" e inclui o texto completo da Apache License 2.0 em seu arquivo LICENSE. Você pode usar, modificar, redistribuir e comercializar o núcleo, sujeito aos requisitos de atribuição e NOTICE (Apache-2.0 §4). O NextPDF Pro e o NextPDF Enterprise são edições comerciais proprietárias e não são cobertos por essa licença. O nome e o logotipo NextPDF são marcas registradas, separadas da licença do código. Consulte Licenciamento do produto.

Qual é a versão mínima de PHP?

PHP 8.4. A restrição do pacote é >=8.4 <9.0, então o Composer se recusa a instalar no PHP 8.3 ou inferior, ou no PHP 9. O NextPDF tem como alvo um único runtime moderno e usa diretamente os recursos de linguagem dele. Consulte Instale o NextPDF.

Ele precisa de um binário externo ou de um navegador headless?

Não, não para o engine do núcleo. O engine nativo é implementado em PHP e extensões PHP padrão, sem nenhum binário de PDF externo e sem nenhum navegador headless obrigatório: a API fluente e o pipeline HTML writeHtml() embutido rodam no mesmo processo, sem navegador e sem chamada de rede. Um binário Chrome ou Chromium é opcional e só é necessário para o renderizador Artisan (writeHtmlChrome()), que você instala separadamente como nextpdf/artisan. As pontes Cloudflare e Gotenberg também são opcionais e chamam um serviço externo. Consulte Escolha seu caminho.

Quais extensões PHP ele exige?

O composer.json do núcleo exige as extensões padrão ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl e ext-openssl, que são extensões PHP comumente disponíveis; garanta que elas estejam instaladas e habilitadas no seu runtime. A ext-curl dá suporte aos round-trips de rede opcionais — carimbo de tempo RFC 3161 e busca de recursos remotos — então a geração nativa offline não a exercita, mas o Composer ainda a lista como um requisito obrigatório. As integrações verificam as de que precisam durante o boot e param com uma mensagem clara se alguma estiver ausente. A lista completa fica no composer.json do pacote; consulte Instale o NextPDF.

Como gero meu primeiro PDF?

Instale o núcleo e construa um documento com a API fluente:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();
$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$document->save(__DIR__ . '/first.pdf');

Veja o passo a passo em Seu primeiro PDF.

Edições e licenciamento

A Core tem algum limite de recurso ou marca d’água?

Não. A Core é o engine open source para o conjunto de recursos da Core, sem marca d’água e sem tela de aviso. Para o conjunto de recursos da Core — geração, inspeção, criptografia, primitivos de saída PDF/A e PDF/UA e assinatura B-B/B-T com chave de software (sem os fluxos Premium de validação de longo prazo e de custódia de chaves) — a Core é completa. A marca d’água de avaliação se aplica apenas a uma concessão de avaliação Premium, em que você testa todo o conjunto de recursos do Pro e do Enterprise por trás de uma marca removível; uma licença paga a remove sem nenhuma mudança no código da aplicação. Consulte Licenciamento e ativação.

Preciso de mudanças no código para atualizar para Pro ou Enterprise?

Na maioria das vezes, não. Quando você instala o nextpdf/premium, as integrações de framework e o servidor o detectam automaticamente e expõem os recursos extras. A maioria das aplicações mantém os mesmos pontos de integração de alto nível; alguns fluxos Premium podem exigir configuração ou chamadas específicas do recurso. Você ativa um envelope de licença assinado uma vez por implantação. Consulte Licenciamento e ativação.

Posso usar o núcleo em um produto comercial de código fechado?

Sim. A Apache License 2.0 não tem restrição não comercial. Você pode usar o núcleo em produtos comerciais de código fechado, pagos ou internos, desde que cumpra as obrigações de atribuição e NOTICE e não trate a licença do código como permissão para usar a marca NextPDF. Consulte Licenciamento do produto e Uso de marca registrada e da marca.

Capacidades

Ele consegue ler e analisar PDFs, ou só escrevê-los?

Ambos, com uma ressalva. O NextPDF escreve PDFs e também os lê: o módulo Inspect lê um arquivo existente para um InspectResult estruturado com dados de complexidade, fontes, imagens e risco, e você pode mesclar e dividir documentos existentes. O Inspect é marcado como experimental, então o formato do seu resultado pode mudar entre versões minor — use-o para diagnóstico e gating, não como um contrato de longa duração. Consulte o módulo Inspect.

Ele produz texto selecionável e pesquisável?

Sim. Tanto a API fluente quanto o pipeline writeHtml() embutido emitem conteúdo de texto real, não imagens rasterizadas, então a saída é selecionável e pesquisável. O writeHtmlChrome() do renderizador Artisan também mantém o texto selecionável. Consulte Seu primeiro PDF.

Como funciona a renderização de HTML e CSS?

O engine do núcleo inclui um pipeline HTML em PHP puro. O writeHtml() renderiza um fragmento HTML com um subconjunto suportado de CSS diretamente na página, sem navegador e sem chamada de rede. Quando um layout precisa de fidelidade total de navegador — como flexbox, grid ou web fonts — instale o renderizador Artisan e chame writeHtmlChrome(). Antes de depender de uma propriedade, consulte a matriz de suporte a CSS.

Como funcionam as fontes?

Os aliases de fontes padrão embutidos, como Helvetica, funcionam sem configuração para texto WinAnsi simples, então seu primeiro documento não precisa de arquivos de fonte. As fontes padrão latinas embutidas servem para texto WinAnsi básico; Symbol e ZapfDingbats usam suas próprias codificações; para renderizar outros sistemas de escrita, você registra e incorpora uma fonte cujo mapa de caracteres e caminho de shaping suportem aquele sistema de escrita. Consulte a matriz de suporte a fontes e o módulo Font.

Ele suporta PDF/A e acessibilidade (PDF/UA)?

Sim, com um limite claro: suporte a um perfil não é conformidade. O núcleo inclui o discriminador de conformidade e os primitivos de tagging — enableTaggedPdf() habilita a saída de estrutura tagged-PDF usada em fluxos PDF/UA, e enablePdfA() seleciona um perfil de saída PDF/A na Core; as edições Premium acrescentam fluxos e ferramental de autoria de arquivamento de nível mais alto (validação, política e operações de produção) por cima. O NextPDF emite os artefatos estruturais que um perfil exige; um validador independente como o veraPDF decide se um determinado arquivo realmente está em conformidade. Consulte Conformidade e o módulo Accessibility.

Como assino um PDF?

O núcleo pode produzir assinaturas Cryptographic Message Syntax (CMS) SignedData e pode aplicar carimbos de tempo RFC 3161 (o nível B-T), usando algoritmos de chave de software suportados por meio do provedor de assinatura configurado. Seu código depende do contrato SignerInterface, então a mesma chamada funciona entre as edições. Os níveis de longo prazo PAdES B-LT e B-LTA, a custódia de chaves HSM e PKCS#11 e as assinaturas qualificadas são recursos Enterprise; os fluxos de assinatura apoiada em cloud e KMS estão na Pro. A Core produz as estruturas baseline B-B e B-T. Consulte o módulo Signing.

Produção

Ele é seguro para workers e thread-safe?

Um Document é de uso único: depois de escrever um, crie uma instância nova para o próximo documento em vez de reutilizá-lo. Isso o torna um encaixe natural para o modelo por requisição, por job usado por PHP-FPM, workers de fila e frameworks — cada unidade de trabalho constrói seu próprio documento. Quando você analisa ou compõe entrada não confiável, execute esse trabalho em um worker restrito e mantenha as proteções de recursos (maxFiles, maxTotalBytes, maxBytes) apertadas. Consulte o módulo Document e o modelo de ameaças do engine.

A saída é determinística?

Ela é estruturalmente determinística, mas não idêntica byte a byte por padrão. Duas execuções da mesma entrada produzem PDFs estruturalmente iguais, mas cada um carrega um trailer e um /ID de documento novos, então os bytes diferem. Assinatura e carimbos de tempo acrescentam mais variação por execução, por design. Planeje suas comparações em torno da igualdade estrutural, ou normalize os campos voláteis, em vez de esperar bytes idênticos entre execuções.

Como faço a implantação?

Comite o composer.lock para que cada worker implantado resolva a mesma versão do engine, depois implante como faria com qualquer biblioteca PHP — a geração nativa não precisa de daemon, navegador ou rede; carimbo de tempo (B-T), recursos remotos ou a ponte de navegador opcional exigem acesso de rede configurado. Se serviços não-PHP precisarem do engine, execute o NextPDF Server, que o expõe por Model Context Protocol (MCP), REST e gRPC. Para o Premium, posicione o envelope de licença assinado onde a implantação o carrega e execute a etapa única de ativação; o estado de licença em cache significa que o processamento normal não precisa de um serviço de licença, então implantações air-gapped são suportadas. Consulte Instale o NextPDF e Licenciamento e ativação.

Para onde levo um problema quando algo dá errado?

O NextPDF reporta erros por classe de exceção PHP, não por um código de erro em string, e as exceções com reconhecimento de contexto carregam campos de diagnóstico estruturados. A base de conhecimento de solução de problemas mapeia as falhas comuns de assinatura, PDF/A, PDF/UA, fontes, tagging e criptografia para sua causa e resolução.