La filosofía de diseño de NextPDF

Spec: ISO/IEC 25010Spec: ISO 32000-2

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.

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.