La philosophie de conception de NextPDF

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

En bref

Cette page énonce les principes à l’aune desquels chaque décision d’API de NextPDF est jugée. Ils sont délibérément peu nombreux, car un principe que tu ne peux pas réciter est un principe que tu ne peux pas appliquer sous pression.

C’est la page à lire en premier. Les autres pages Insider_ montrent ces principes à l’œuvre à des endroits précis. Celle-ci les nomme pour que le reste prenne son sens.

Pourquoi c’est important

Le PDF est assez ancien pour avoir des convictions, et assez strict pour sanctionner les suppositions. Une signature couvre exactement les octets qu’elle couvre. Une police est intégrée ou elle ne l’est pas. Un profil d’archivage tient, ou il échoue à un audit des mois plus tard, devant quelqu’un qui a besoin de preuves.

Une bibliothèque a le choix lorsque les entrées sont ambiguës. Elle peut deviner et rester silencieuse, ou elle peut s’arrêter et le dire. La première option paraît plus accueillante dans une démo. Elle peut aussi te coûter un incident de production sans aucune trace de ce qui a mal tourné. NextPDF choisit la seconde. Elle accepte une première impression moins rassurante en échange d’une impression défendable. Les normes de qualité logicielle nomment ce compromis sans détour. Le comportement fail-safe est la capacité d’un produit à revenir à un état sûr en cas de défaillance plutôt que de continuer dans un état indéfini (Spec: ISO/IEC 25010, §3).

La version courte

NextPDF repose sur cinq principes, par ordre de priorité :

L’explicite l’emporte sur l’implicite. Si l’intention compte, tu la déclares. Le moteur ne déduit pas du contexte un niveau de signature, un mode de sortie ou une cible de conformité.
Échouer vite, échouer fort, échouer tôt. Une entrée invalide est rejetée avant qu’un seul octet ne soit écrit, avec un message qui nomme la cause.
Les erreurs sont une surface d’API. Les défaillances sont spécifiques, typées et portent un contexte structuré — conçues, non fortuites.
Les frontières sont énoncées, pas découvertes. Chaque affirmation dit où elle s’arrête. « Nécessaire, mais pas suffisant » est une formule que NextPDF énonce à dessein.
Rien ne se dégrade en silence. Le moteur ne renvoie pas un artefact à demi correct qui a l’air terminé.

Tout le reste — le constructeur fluide, le document jetable, le typage strict — découle de ces principes.

Comment NextPDF l’aborde

Les principes ne sont pas des slogans. Ils prennent des formes concrètes dans le code source, et ils se renforcent mutuellement.

Le tableau ci-dessous associe chaque principe à l’endroit où tu peux l’observer dans le moteur et à ce qu’il en coûte lorsqu’il est absent.

Principe	Comment cela se manifeste dans NextPDF	Le coût du contraire
L’explicite l’emporte sur l’implicite	`setSignature(certInfo:, level:)` prend le niveau PAdES comme argument nommé et obligatoire — il n’existe pas de niveau « auto »	Un document signé selon un profil que l’obligation n’exigeait pas, découvert au moment de la validation
Échouer vite, échouer fort	`save()` rejette un chemin à wrapper de flux ou à octet nul avant tout rendu ; `setSignature()` suivi de `save()` lève une exception au lieu de produire un fichier non signé	Une écriture par traversée de chemin, ou un PDF « non signé mais réputé signé » dans une archive
Les erreurs sont une surface d’API	Une exception de base abstraite, des sous-classes typées spécifiques, chacune exposant un `getContext()` structuré pour les journaux et l’APM	Une trace de pile générique et un long après-midi de suppositions
Les frontières sont énoncées	Les vérifications de conformité en cours de traitement renvoient des constats et disent en toutes lettres que le verdict revient à un validateur indépendant	Une conclusion « aucune exception, donc c’est forcément conforme » qu’un auditeur réfute
Rien ne se dégrade en silence	Le chemin d’horodatage d’archivage refuse de renvoyer un profil à demi écrit plutôt que d’en produire un auquel il manque son dictionnaire requis	Un profil de validation à long terme qui, discrètement, n’en est pas un

Lis les principes ensemble et une posture unique se dégage : le moteur préfère te donner un « non » honnête plutôt qu’un « peut-être » assuré. Ce n’est pas du pessimisme. C’est reconnaître qu’un PDF est souvent un artefact à valeur légale. Un artefact légal erroné est pire qu’un artefact qui n’a jamais été produit.

Exemple pratique

Les principes se voient en quelques lignes d’usage ordinaire. L’appel de signature déclare explicitement l’intention. Le moteur refuse tôt plutôt que de produire quelque chose de trompeur.

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

Le propos n’est pas la mécanique de la signature. Trois principes sont observables dans un seul extrait : l’intention est déclarée (level:), l’échec est précoce et nommé, et le moteur refuse de produire un document qui mentirait sur son propre état.

Idée fausse courante

Le contresens le plus fréquent, c’est de croire que ces principes rendent NextPDF « plus difficile à utiliser ». Ils le rendent plus difficile à mal utiliser. Un argument obligatoire, c’est une valeur par défaut silencieuse de moins qui te surprendra. Une exception précoce, c’est un artefact corrompu de moins dans une archive. La friction est délibérément placée là où une erreur coûte peu — au site d’appel, en développement — au lieu de là où elle coûte cher : en production, lors d’un audit, au tribunal.

Un second contresens consiste à croire qu’« avoir des convictions » signifie « être rigide ». Ce n’est pas le cas. Le moteur a des convictions sur la justesse et l’intention, pas sur ton document. Tu gardes un contrôle total sur la mise en page, le contenu, les polices et la structure. Ses convictions portent sur le fait de ne pas deviner à ta place là où deviner serait dangereux.

Limites et frontières

Cette page énonce une intention de conception. Elle n’est pas elle-même une spécification comportementale. Les principes décrivent comment les décisions sont prises, pas une garantie sur une méthode particulière. Le contrat exact de chaque méthode se trouve dans la référence et dans sa propre page Insider_, avec le niveau de preuve de cette page.

Les principes ne sont pas non plus des lois physiques absolues. Ce sont des priorités, appliquées avec discernement. Lorsque deux principes s’opposent (un refus plus strict contre une valeur par défaut plus tolérante), l’ordre de priorité ci-dessus tranche. Un module donné peut tout de même documenter une exception raisonnée. Quand c’est le cas, cette exception est écrite noir sur blanc, pas supposée.

Enfin, « principe de conception » est la base probante ici, à dessein. Cette page argumente. Elle ne mesure pas. Les affirmations qui exigent un chiffre, un test ou une clause pour être étayées figurent sur les pages qui détiennent cette preuve, pas ici.

Documents liés

Une API qui refuse de deviner — les principes d’intention explicite et de fail-fast, illustrés face à la vraie API.
Les erreurs comme fonctionnalité — la hiérarchie d’exceptions typées en tant que surface conçue.
Les fondations PHP 8.4 — les fonctionnalités du langage qui permettent d’imposer ces principes plutôt que de les espérer.

Glossaire

Principe de conception (niveau de preuve) — une page dont les affirmations sont des décisions de conception délibérées, argumentées à partir de l’intention et de normes corroborantes plutôt que mesurées par un banc d’essai ou un test unique.
Fail-safe — une propriété de qualité logicielle : en cas de défaillance, le produit revient à un état sûr au lieu de continuer dans un état indéfini. La raison pour laquelle NextPDF refuse plutôt que de deviner.
Fail fast — rejeter une entrée invalide au point le plus précoce possible, avec une cause claire, au lieu de poursuivre et d’échouer obscurément plus tard.
PAdES — PDF Advanced Electronic Signatures, la famille de profils ETSI pour la signature de documents PDF (B-B, B-T, B-LT, B-LTA). Développé ici à la première utilisation ; traité en profondeur sur les pages de signature.
Nécessaire, mais pas suffisant — une formulation délibérée employée lorsqu’une vérification en cours de traitement est un vrai signal mais pas un verdict de conformité ; la décision faisant autorité revient à un validateur indépendant.