La filosofía de diseño de NextPDF

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

De un vistazo

Esta página presenta los principios frente a los que se evalúa cada decisión de la API de NextPDF. Son deliberadamente pocos, porque un principio que no se puede recordar de memoria no se puede aplicar bajo presión.

Es la página que conviene leer primero. El resto de páginas Insider_ muestran estos principios en acción en lugares concretos. Esta los nombra para que todo lo demás cobre sentido.

Por qué esto importa

El PDF es lo bastante antiguo como para tener criterios firmes y lo bastante estricto como para castigar las conjeturas. Una firma cubre exactamente los bytes que cubre. Una fuente está incrustada o no lo está. Un perfil de archivo se sostiene o falla en una auditoría meses después, ante alguien que no estará de buen humor.

Una biblioteca se encuentra ante una elección cuando las entradas son ambiguas. Puede conjeturar y callar, o puede detenerse y decirlo. Lo primero resulta más amable en una demostración. También acaba costando un incidente en producción sin rastro alguno de qué salió mal. NextPDF elige lo segundo. Acepta una primera impresión menos tranquilizadora a cambio de otra defendible. Las normas de calidad del software dan nombre a esta disyuntiva directamente. El comportamiento a prueba de fallos es la capacidad de un producto de volver a un estado seguro ante un fallo en lugar de continuar en uno indefinido ( Spec: ISO/IEC 25010, §3 ).

La versión breve

NextPDF se asienta sobre cinco principios, en orden de prioridad:

Lo explícito gana a lo implícito. Si la intención importa, se declara. El motor no infiere del contexto un nivel de firma, un modo de salida ni un objetivo de conformidad.
Fallar rápido, de forma visible y cuanto antes. Una entrada no válida se rechaza antes de escribir un solo byte, con un mensaje que nombra la causa.
Los errores son una superficie de la API. Los fallos son específicos, tipados e incluyen contexto estructurado: diseñados, no accidentales.
Los límites se declaran, no se descubren. Cada afirmación dice dónde se detiene. «Necesario, no suficiente» es una expresión que NextPDF emplea a propósito.
Nada se degrada en silencio. El motor no devuelve un artefacto a medias que aparenta estar terminado.

Todo lo demás —el constructor fluido, el documento desechable, el tipado estricto— se deriva de ellos.

Cómo lo aborda NextPDF

Los principios no son carteles. Se concretan en el código y se refuerzan mutuamente.

La tabla siguiente relaciona cada principio con el lugar donde se observa en el motor y con lo que cuesta cuando está ausente.

Principio	Cómo se manifiesta en NextPDF	El coste de lo contrario
Lo explícito gana a lo implícito	`setSignature(certInfo:, level:)` recibe el nivel PAdES como argumento obligatorio y con nombre: no existe un nivel «auto»	Un documento firmado con un perfil que la obligación no exigía y que se descubre en el momento de la validación
Fallar rápido, fallar a la vista	`save()` rechaza una ruta con envoltorio de flujo o con byte nulo antes de renderizar; `setSignature()` seguido de `save()` lanza una excepción en lugar de emitir un archivo sin firmar	Una escritura con salto de ruta (path traversal), o un PDF «sin firmar pero que se cree firmado» en un archivo
Los errores son una superficie de la API	Una única excepción base abstracta, con subclases tipadas específicas; cada una expone un `getContext()` estructurado para los registros y el APM	Una traza de pila genérica y una larga tarde de conjeturas
Los límites se declaran	Las comprobaciones de conformidad en el propio proceso devuelven hallazgos y declaran expresamente que el veredicto corresponde a un validador independiente	Una conclusión del tipo «no hubo excepción, así que debe de ser conforme» que un auditor refuta
Nada se degrada en silencio	La ruta de marca de tiempo de archivo se niega a devolver un perfil escrito a medias en lugar de emitir uno al que le falte su diccionario obligatorio	Un perfil de validación a largo plazo que, en silencio, no lo es

Leídos en conjunto, los principios revelan una sola postura: el motor prefiere devolver un «no» honesto antes que un «quizá» confiado. Eso no es pesimismo. Es el reconocimiento de que un PDF es, con frecuencia, un artefacto legal. Un artefacto legal incorrecto es peor que uno que nunca se produjo.

Qué dice la evidencia

Esta página es una declaración de Evidence: Design principle : los principios son decisiones deliberadas, más argumentadas que medidas. Allí donde un principio tiene un nombre en una disciplina externa, la página se apoya en él para que el razonamiento no sea una mera opinión interna.

La postura de «negarse antes que continuar en un estado indefinido» es la propiedad de calidad a prueba de fallos del §3 de Spec: ISO/IEC 25010 : un producto que queda en una condición segura ante un fallo. La tolerancia a fallos, dentro de la misma familia, es el grado en que un sistema sigue comportándose según lo previsto pese a los fallos. NextPDF orienta ese esfuerzo hacia detectar el fallo y detenerse, no hacia ocultarlo.
La postura de «declarar el límite antes de la adopción» es el reconocimiento de idoneidad ( Spec: ISO/IEC 25010, §3.26 ): la capacidad de juzgar el encaje a partir de la documentación y de las primeras impresiones.
La razón específica del PDF por la que todo esto importa es Spec: ISO 32000-2, §12.8 : el rango de bytes de una firma protege exactamente los bytes que cubre y nada más, de modo que un motor que «amablemente» reescribe o conjetura en torno a un documento firmado no ha ayudado en nada.

Los principios individuales se demuestran frente al código real del motor en sus propias páginas: Una API que se niega a conjeturar y Los errores como funcionalidad aportan la prueba Evidence: Code-backed . Esta página explica el porqué; esas páginas, el qué.

Ejemplo práctico

Los principios se aprecian en unas pocas líneas de uso habitual. La llamada de firma declara la intención de manera explícita. El motor se niega pronto en lugar de emitir algo engañoso.

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

Lo importante no es la mecánica de la firma, sino que se observan tres principios en un solo fragmento: la intención se declara (level:), el fallo se produce pronto y con una causa explícita, y el motor se niega a producir un documento que mentiría sobre su propio estado.

Concepto erróneo habitual

La lectura errónea más habitual es que estos principios hacen que NextPDF sea «más difícil de usar». Lo que hacen es que sea más difícil usarlo mal. Un argumento obligatorio es un valor por defecto silencioso menos por el que llevarse una sorpresa. Una excepción temprana significa un artefacto corrupto menos en un archivo. La fricción se coloca deliberadamente donde un error sale barato —en el punto de llamada, durante el desarrollo— en lugar de donde sale caro: en producción, en una auditoría, en un tribunal.

Una segunda lectura errónea es que «con criterio firme» signifique «inflexible». No es así. El motor tiene criterios sobre la corrección y la intención, no sobre el documento. El control del diseño, el contenido, las fuentes y la estructura sigue siendo completo. Los criterios versan sobre no conjeturar en nombre del usuario allí donde una conjetura sería insegura.

Límites y fronteras

Esta página enuncia la intención de diseño. No es, en sí misma, una especificación de comportamiento. Los principios describen cómo se toman las decisiones, no una garantía sobre ningún método concreto. El contrato preciso de cada método reside en la referencia y en su propia página Insider_, con el nivel de evidencia de esa página.

Los principios tampoco son leyes absolutas de la física. Son prioridades, aplicadas con criterio. Cuando dos principios entran en conflicto (un rechazo más estricto frente a un valor por defecto más permisivo), el orden de prioridad anterior decide el desempate. Un módulo concreto puede, aun así, documentar una excepción razonada. Cuando lo hace, esa excepción se deja por escrito, no se da por supuesta.

Por último, aquí «principio de diseño» es, deliberadamente, la base de evidencia. Esta página argumenta. No mide rendimiento. Las afirmaciones que necesitan un número, una prueba o una cláusula para sostenerse se hacen en las páginas que cuentan con esa evidencia, no aquí.

Documentos relacionados

Una API que se niega a conjeturar: los principios de intención explícita y de fallar rápido, demostrados con la API real.
Los errores como funcionalidad: la jerarquía de excepciones tipadas como superficie diseñada.
Los cimientos de PHP 8.4: las funcionalidades del lenguaje que permiten hacer cumplir estos principios en lugar de solo esperarlos.

Glosario

Principio de diseño (nivel de evidencia): una página cuyas afirmaciones son decisiones de diseño deliberadas, argumentadas a partir de la intención y de normas que las respaldan, más que medidas mediante un banco de pruebas o una sola prueba.
A prueba de fallos: una propiedad de calidad del software: ante un fallo, el producto vuelve a un estado seguro en lugar de continuar en uno indefinido. La razón por la que NextPDF se niega en lugar de conjeturar.
Fallar rápido: rechazar una entrada no válida en el punto más temprano posible, con una causa clara, en lugar de proseguir y fallar de forma oscura más adelante.
PAdES: PDF Advanced Electronic Signatures, la familia de perfiles de ETSI para firmar documentos PDF (B-B, B-T, B-LT, B-LTA). Aquí se escribe completo en su primer uso; se trata en profundidad en las páginas de firma.
Necesario, no suficiente: una formulación deliberada que se emplea cuando una comprobación en el propio proceso es una señal real pero no un veredicto de conformidad; la decisión autorizada corresponde a un validador independiente.