A filosofia de design do NextPDF

Spec: ISO/IEC 25010 Spec: ISO 32000-2 Evidence: Design principle

Visão geral

Esta página apresenta os princípios pelos quais toda decisão de API do NextPDF é avaliada. Eles são deliberadamente poucos, porque um princípio que você não consegue recitar é um princípio que você não consegue aplicar sob pressão.

Esta é a página para ler primeiro. As outras páginas Insider_ mostram esses princípios em ação em pontos específicos. Esta os nomeia para que o restante faça sentido.

Por que isso importa

O PDF é antigo o suficiente para ter opiniões e rigoroso o suficiente para punir palpites. Uma assinatura cobre exatamente os bytes que cobre. Uma fonte ou está incorporada ou não está. Um perfil de arquivamento ou se sustenta ou falha em uma auditoria meses depois, diante de alguém que precisa de evidências.

Uma biblioteca precisa escolher quando as entradas são ambíguas. Ela pode dar um palpite e se calar, ou pode parar e dizer o que aconteceu. A primeira opção parece mais amigável em uma demonstração. Ela também pode lhe custar um incidente em produção sem nenhum rastro do que deu errado. O NextPDF escolhe a segunda. Ele aceita uma primeira impressão menos tranquilizadora em troca de uma postura defensável. Os padrões de qualidade de software dão nome a essa troca diretamente. O comportamento fail-safe (à prova de falhas) é a capacidade de um produto de reverter a um estado seguro em caso de falha, em vez de continuar em um estado indefinido ( Spec: ISO/IEC 25010, §3 ).

A versão resumida

O NextPDF é construído sobre cinco princípios, em ordem de prioridade:

Explícito vence implícito. Se a intenção importa, você a declara. O motor não infere um nível de assinatura, um modo de saída ou um alvo de conformidade a partir do contexto.
Falhe rápido, falhe de forma explícita, falhe cedo. Uma entrada inválida é rejeitada antes que um byte seja escrito, com uma mensagem que nomeia a causa.
Erros são uma superfície de API. As falhas são específicas, tipadas e carregam contexto estruturado — projetadas, não incidentais.
Os limites são declarados, não descobertos. Toda afirmação diz onde ela termina. “Necessário, não suficiente” é uma frase que o NextPDF declara de propósito.
Nada se degrada silenciosamente. O motor não retorna um artefato meio correto que parece finalizado.

Todo o restante — o builder fluente, o documento descartável, a tipagem estrita — decorre desses princípios.

Como o NextPDF aborda isso

Os princípios não são slogans. Eles aparecem de forma concreta no código-fonte e se reforçam mutuamente.

A tabela abaixo mapeia cada princípio ao lugar onde você pode vê-lo no motor e ao que custa se ele estiver ausente.

Princípio	Como aparece no NextPDF	O custo do oposto
Explícito vence implícito	`setSignature(certInfo:, level:)` recebe o nível PAdES como um argumento nomeado e obrigatório — não existe nível “auto”	Um documento assinado em um perfil que a obrigação não exigia, descoberto no momento da validação
Falhe rápido, falhe de forma explícita	`save()` rejeita um caminho com stream-wrapper ou byte nulo antes da renderização; `setSignature()` seguido de `save()` lança uma exceção em vez de emitir um arquivo não assinado	Uma escrita com path traversal, ou um PDF “não assinado, mas tido como assinado” em um arquivo morto
Erros são uma superfície de API	Uma exceção base abstrata, subclasses tipadas específicas, cada uma expondo um `getContext()` estruturado para logs e APM	Um stack trace genérico e uma longa tarde de adivinhação
Os limites são declarados	As verificações de conformidade em processo retornam constatações e dizem em palavras que o veredito pertence a um validador independente	Uma conclusão do tipo “nenhuma exceção, então deve estar em conformidade” que um auditor refuta
Nada se degrada silenciosamente	O caminho do carimbo de tempo de arquivamento se recusa a retornar um perfil escrito pela metade em vez de emitir um sem o dicionário obrigatório	Um perfil de validação de longo prazo que, silenciosamente, não é um

Lidos em conjunto, os princípios revelam uma única postura: o motor prefere lhe dar um “não” honesto a um “talvez” confiante. Isso não é pessimismo. É reconhecer que um PDF é, muitas vezes, um artefato jurídico. Um artefato jurídico errado é pior do que um que nunca foi produzido.

O que as evidências dizem

Esta página é uma declaração Evidence: Design principle : os princípios são decisões deliberadas, sustentadas por argumentos em vez de medidas. Quando um princípio tem nome em uma disciplina externa, a página se ancora nele para que o raciocínio não seja apenas uma opinião interna.

A postura de “recusar em vez de continuar em um estado indefinido” é a propriedade de qualidade fail-safe (à prova de falhas) na Spec: ISO/IEC 25010 §3 — um produto que se coloca em uma condição segura em caso de falha. A tolerância a falhas, na mesma família, é o grau em que um sistema continua se comportando como pretendido apesar das falhas. O NextPDF direciona esse esforço para detectar e parar, não para ocultar a falha.
A postura de “declarar o limite antes da adoção” é a reconhecibilidade de adequação ( Spec: ISO/IEC 25010, §3.26 ): a capacidade de avaliar a adequação a partir da documentação e das primeiras impressões.
A razão específica do PDF pela qual algo disso importa é a Spec: ISO 32000-2, §12.8 : o byte range de uma assinatura protege exatamente os bytes que cobre e nada mais, de modo que um motor que “prestativamente” reescreve ou adivinha em torno de um documento assinado não ajudou em nada.

Os princípios individuais são demonstrados com base no código-fonte real do motor em suas próprias páginas — Uma API que se recusa a adivinhar e Erros como recurso trazem a Evidence: Code-backed prova. Esta página é o porquê; aquelas páginas são o quê.

Exemplo prático

Os princípios são visíveis em algumas linhas de uso comum. A chamada de assinatura declara a intenção explicitamente. O motor recusa cedo em vez de emitir algo enganoso.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Exception\NotImplementedException;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;

$document = Document::createStandalone();
$document->setTitle('Service Agreement 2026-0042');
$document->addPage();
$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This agreement is configured for a PAdES signature.', newLine: true);

// Explicit beats implicit: the PAdES level is a required, named argument.
// There is no inferred or "auto" level.
$document->setSignature(
    certInfo: new CertificateInfo(
        certificate: $certificatePem,
        privateKey: $privateKeyPem,
    ),
    level: SignatureLevel::PAdES_B_B,
);

try {
    // Fail fast, no silent degradation: rather than emit an UNSIGNED file
    // that the caller believes setSignature() signed, the high-level path
    // refuses and names the supported route.
    $document->save('/srv/output/agreement.pdf');
} catch (NotImplementedException $e) {
    // The message identifies the feature and the follow-up, not a stack
    // trace: "... is not implemented in this release. <actionable follow-up>"
    error_log($e->getMessage());
}

O ponto não é a mecânica da assinatura. Três princípios aparecem em um único trecho: a intenção é declarada (level:), a falha é precoce e nomeada, e o motor se recusa a produzir um documento que mentiria sobre o próprio estado.

Equívoco comum

A interpretação equivocada mais comum é que esses princípios tornam o NextPDF “mais difícil de usar”. Eles o tornam mais difícil de usar de forma errada. Um argumento obrigatório é um valor padrão silencioso a menos para surpreender você. Uma exceção precoce é um artefato corrompido a menos em um arquivo morto. A fricção é colocada deliberadamente onde um erro é barato — no ponto de chamada, no desenvolvimento — em vez de onde é caro: em produção, em uma auditoria, em um tribunal.

Uma segunda interpretação equivocada é que “opinativo” significa “inflexível”. Não significa. O motor tem opiniões sobre correção e intenção, não sobre o documento. Você continua controlando completamente o layout, o conteúdo, as fontes e a estrutura. As opiniões existem para não dar palpites em seu nome quando um palpite seria inseguro.

Limites e fronteiras

Esta página declara a intenção de design. Ela não é, por si só, uma especificação comportamental. Os princípios descrevem como as decisões são tomadas, não uma garantia sobre qualquer método específico. O contrato exato de cada método está na referência e em sua própria página Insider_, com o nível de evidência dessa página.

Os princípios também não são leis absolutas da física. São prioridades, aplicadas com discernimento. Quando dois princípios entram em conflito (uma recusa mais rigorosa versus um padrão mais tolerante), a ordem de prioridade acima é o critério de desempate. Um módulo específico ainda pode documentar uma exceção fundamentada. Quando faz isso, essa exceção é registrada por escrito, não presumida.

Por fim, “princípio de design” é a base de evidência aqui, por design. Esta página argumenta. Ela não faz benchmark. Afirmações que precisam de um número, um teste ou uma cláusula para se sustentar são feitas nas páginas que detêm essa evidência, não aqui.

Documentos relacionados

Uma API que se recusa a adivinhar — os princípios de intenção explícita e fail-fast, demonstrados contra a API real.
Erros como recurso — a hierarquia de exceções tipadas como uma superfície projetada.
Os fundamentos do PHP 8.4 — os recursos da linguagem que permitem impor esses princípios, em vez de apenas esperar por eles.

Glossário

Princípio de design (nível de evidência) — uma página cujas afirmações são decisões deliberadas de design, sustentadas pela intenção e por padrões corroborantes, em vez de medidas por um benchmark ou por um único teste.
Fail-safe — uma propriedade de qualidade de software: em caso de falha, o produto reverte a um estado seguro em vez de continuar em um estado indefinido. A razão pela qual o NextPDF recusa em vez de adivinhar.
Fail fast — rejeitar uma entrada inválida no ponto mais cedo possível, com uma causa clara, em vez de prosseguir e falhar obscuramente mais tarde.
PAdES — PDF Advanced Electronic Signatures, a família de perfis da ETSI para assinar documentos PDF (B-B, B-T, B-LT, B-LTA). Expandido aqui no primeiro uso; abordado em profundidade nas páginas de assinatura.
Necessário, não suficiente — uma formulação deliberada usada quando uma verificação em processo é um sinal real, mas não um veredito de conformidade; a decisão autoritativa pertence a um validador independente.