La filosofia progettuale di NextPDF

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

In breve

Questa pagina enuncia i principi con cui viene verificata ogni decisione relativa alle API di NextPDF. Sono pochi per scelta: un principio che non si riesce a ripetere a memoria non si riesce nemmeno ad applicare sotto pressione.

È la pagina da leggere per prima. Le altre pagine Insider_ mostrano questi principi all’opera in contesti specifici; questa li nomina, così che il resto acquisti senso.

Perché è importante

Il PDF esiste da abbastanza tempo da avere posizioni precise ed è abbastanza rigoroso da punire le ipotesi. Una firma copre esattamente i byte che copre. Un font o è incorporato o non lo è. Un profilo di archiviazione o regge oppure fallisce un audit mesi dopo, davanti a qualcuno che non la prende bene.

Davanti a input ambigui, una libreria ha una scelta: può formulare un’ipotesi e tacere, oppure può fermarsi e dichiararlo. La prima opzione appare più cordiale in una demo. In produzione, però, può costare un incidente senza lasciare alcuna traccia di che cosa sia andato storto. NextPDF sceglie la seconda: accetta una prima impressione meno rassicurante in cambio di una difendibile. Gli standard di qualità del software danno un nome preciso a questo compromesso. Il comportamento fail-safe è la capacità di un prodotto di tornare a uno stato sicuro in caso di guasto anziché proseguire in uno indefinito ( Spec: ISO/IEC 25010, §3 ).

La versione breve

NextPDF si fonda su cinque principi, in ordine di priorità:

L’esplicito batte l’implicito. Se l’intento conta, lo si dichiara. Il motore non desume dal contesto un livello di firma, una modalità di output o un obiettivo di conformità.
Fallire presto, fallire in modo evidente, fallire all’inizio. Un input non valido viene rifiutato prima che venga scritto un solo byte, con un messaggio che ne nomina la causa.
Gli errori sono una superficie dell’API. I guasti sono specifici, tipizzati e portano con sé un contesto strutturato: progettati, non incidentali.
I confini si dichiarano, non si scoprono. Ogni affermazione dichiara dove si ferma. «Necessario, non sufficiente» è un’espressione che NextPDF usa di proposito.
Nulla si degrada in silenzio. Il motore non restituisce un artefatto parzialmente corretto che sembra finito.

Tutto il resto — il builder fluente, il documento usa e getta, la tipizzazione rigorosa — deriva da questi principi.

Come NextPDF lo affronta

I principi non sono manifesti da appendere al muro. Prendono forma concreta nel codice sorgente e si rafforzano a vicenda.

La tabella seguente mette in corrispondenza ogni principio con il punto in cui lo si può osservare nel motore e con ciò che costa quando manca.

Principio	Come si manifesta in NextPDF	Il costo del contrario
L’esplicito batte l’implicito	`setSignature(certInfo:, level:)` riceve il livello PAdES come argomento obbligatorio e con nome: non esiste un livello «auto»	Un documento firmato con un profilo che l’obbligo non richiedeva, scoperto al momento della convalida
Fallire presto, fallire in modo evidente	`save()` rifiuta un percorso con stream wrapper o byte null prima del rendering; `setSignature()` seguito da `save()` solleva un’eccezione anziché emettere un file non firmato	Una scrittura con path traversal, oppure un PDF «non firmato ma creduto firmato» in un archivio
Gli errori sono una superficie dell’API	Un’unica eccezione base astratta, sottoclassi specifiche e tipizzate, ciascuna delle quali espone un `getContext()` strutturato per i log e l’APM	Uno stack trace generico e un lungo pomeriggio passato a tirare a indovinare
I confini si dichiarano	I controlli di conformità in-process restituiscono rilievi e dichiarano esplicitamente che il verdetto spetta a un validatore indipendente	Una conclusione del tipo «nessuna eccezione, quindi dev’essere conforme» che un revisore smentisce
Nulla si degrada in silenzio	Il percorso della marca temporale di archiviazione si rifiuta di restituire un profilo scritto a metà anziché emetterne uno privo del dizionario richiesto	Un profilo di convalida a lungo termine che, in silenzio, non lo è

Nel loro insieme, i principi rivelano un’unica posizione: il motore preferisce darti un «no» onesto piuttosto che un «forse» sicuro. Non è pessimismo. È il riconoscimento che un PDF è spesso un artefatto giuridico. Un artefatto giuridico errato è peggiore di uno che non è mai stato prodotto.

Cosa dicono le prove

Questa pagina è una dichiarazione Evidence: Design principle : i principi sono decisioni deliberate, argomentate anziché misurate. Quando un principio ha un nome in una disciplina esterna, la pagina vi si ancora, così che il ragionamento non resti una semplice opinione interna.

La posizione «rifiutare anziché proseguire in uno stato indefinito» corrisponde alla proprietà di qualità fail-safe nella Spec: ISO/IEC 25010 §3: un prodotto che si pone in una condizione sicura in caso di guasto. La tolleranza ai guasti, nella stessa famiglia, è il grado in cui un sistema continua a comportarsi come previsto nonostante i guasti. NextPDF indirizza quello sforzo verso il rilevamento e l’arresto, non verso l’occultamento del guasto.
La posizione «dichiarare il confine prima dell’adozione» corrisponde alla riconoscibilità dell’adeguatezza ( Spec: ISO/IEC 25010, §3.26 ): la capacità di giudicare l’idoneità a partire dalla documentazione e dalle prime impressioni.
La ragione specifica per cui, nel PDF, tutto questo conta è la Spec: ISO 32000-2, §12.8 : il byte range di una firma protegge esattamente i byte che copre e nulla di più, perciò un motore che riscrive in modo «premuroso» un documento firmato, o tira a indovinare attorno a esso, non ha aiutato affatto.

I singoli principi sono dimostrati nel codice sorgente reale del motore nelle rispettive pagine: Un’API che si rifiuta di tirare a indovinare ed Gli errori come funzionalità forniscono la Evidence: Code-backed prova. Questa pagina è il perché; quelle pagine sono il cosa.

Esempio pratico

Bastano poche righe di uso ordinario per vedere i principi all’opera. La chiamata per la firma dichiara l’intento in modo esplicito. Il motore si rifiuta presto anziché emettere qualcosa di fuorviante.

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

Il punto non è la meccanica della firma. È che tre principi sono osservabili in un solo frammento: l’intento viene dichiarato (level:), il guasto è precoce e nominato, e il motore si rifiuta di produrre un documento che mentirebbe sul proprio stato.

Equivoco frequente

L’equivoco più frequente è che questi principi rendano NextPDF «più difficile da usare». Lo rendono più difficile da usare in modo sbagliato. Un argomento obbligatorio è un valore predefinito silenzioso in meno da cui farsi sorprendere. Un’eccezione precoce è un artefatto corrotto in meno in un archivio. L’attrito è collocato di proposito dove un errore costa poco — nel punto di chiamata, in fase di sviluppo — anziché dove costa caro: in produzione, in un audit, in tribunale.

Un secondo equivoco è che «con posizioni precise» significhi «rigido». Non è così. Il motore ha posizioni precise su correttezza e intento, non sul tuo documento. Layout, contenuto, font e struttura restano interamente sotto il tuo controllo. Le posizioni precise riguardano il fatto di non tirare a indovinare per tuo conto là dove un’ipotesi sarebbe insicura.

Limiti e confini

Questa pagina enuncia l’intento di progettazione. Non è, di per sé, una specifica comportamentale. I principi descrivono come vengono prese le decisioni, non garantiscono il comportamento di un singolo metodo. Il contratto esatto di ciascun metodo si trova nel riferimento e nella relativa pagina Insider_, con il livello di prova proprio di quella pagina.

I principi non sono nemmeno leggi assolute della fisica. Sono priorità, applicate con discernimento. Quando due principi sono in conflitto (un rifiuto più rigoroso contro un valore predefinito più indulgente), l’ordine di priorità di cui sopra dirime la questione. Un modulo specifico può comunque documentare un’eccezione motivata. Quando lo fa, quell’eccezione viene messa per iscritto, non data per scontata.

Infine, «principio di progettazione» è la base di prova adottata qui per scelta. Questa pagina argomenta. Non esegue benchmark. Le affermazioni che richiedono un numero, un test o una clausola a sostegno si trovano nelle pagine che possiedono quella prova, non qui.

Documenti correlati

Un’API che si rifiuta di tirare a indovinare — i principi dell’intento esplicito e del fail-fast, mostrati nell’API reale.
Gli errori come funzionalità — la gerarchia di eccezioni tipizzate come superficie progettata.
Le fondamenta di PHP 8.4 — le funzionalità del linguaggio che consentono di imporre questi principi anziché limitarsi a sperare che vengano rispettati.

Glossario

Principio di progettazione (livello di prova) — una pagina le cui affermazioni sono decisioni di progettazione deliberate, argomentate a partire dall’intento e da standard di supporto anziché misurate con un benchmark o un singolo test.
Fail-safe — una proprietà di qualità del software: in caso di guasto, il prodotto ritorna a uno stato sicuro invece di proseguire in uno indefinito. La ragione per cui NextPDF si rifiuta anziché tirare a indovinare.
Fail fast — rifiutare un input non valido nel punto più precoce possibile, con una causa chiara, invece di proseguire e fallire in modo oscuro più avanti.
PAdES — PDF Advanced Electronic Signatures, la famiglia di profili ETSI per la firma di documenti PDF (B-B, B-T, B-LT, B-LTA). Spiegata qui al primo uso; trattata in profondità nelle pagine sulla firma.
Necessario, non sufficiente — una formulazione deliberata usata quando un controllo in-process è un segnale reale ma non un verdetto di conformità; la decisione autorevole spetta a un validatore indipendente.