Convenzioni delle ricette

Ogni ricetta eseguibile del ricettario di integrazione segue lo stesso contratto. Questa pagina lo documenta, così che chi legge sappia cosa aspettarsi da una ricetta e chi scrive sappia quali requisiti deve soddisfare. La pagina ha valore descrittivo: documenta la convenzione. L’applicazione concreta risiede negli strumenti del repository e nel foglio di override dello stile, non qui.

Il repository sorgente di ogni integrazione contiene le proprie ricette in docs/public/ e l’aggregatore le importa in questo sito. Le convenzioni riportate di seguito si applicano a una ricetta ovunque si trovi.

1. Gli esempi sono codice reale, non frammenti inseriti a mano

Il codice di una ricetta è codice reale presente in un repository, non un frammento inserito direttamente nel testo.

Qualsiasi blocco di codice PHP più lungo di cinque righe proviene da una directory examples/ del repository corrispondente oppure da una directory tests/Cookbook/.
Il blocco dichiara la propria origine nell’info string del blocco delimitato, ad esempio title="examples/standalone.php".
Un test corrispondente verifica che l’esempio compili ancora e continui a produrre l’output documentato, in modo che la pagina renderizzata non possa divergere dal codice mostrato.

Questa convenzione corrisponde al foglio di override dello stile della documentazione §3.4 («Gli esempi devono essere eseguibili»). Una ricetta che mostra codice senza un esempio o un test di supporto non rispetta la convenzione.

2. Un linguaggio per blocco, con gestione degli errori visibile

Un blocco di codice delimitato contiene esattamente un solo linguaggio, dichiarato in modo esplicito ( ```php, ```bash, ```yaml, ```json). Non si usano delimitatori senza linguaggio.
Una ricetta contrassegnata come how-to pronto per la produzione mostra esplicitamente try / catch, intercetta il tipo di eccezione applicabile più specifico invece di un \Exception generico, e nel blocco catch esegue un’azione che chi legge può copiare (registrare un log, rilanciare l’eccezione o restituire un oggetto di errore definito). Non si usano blocchi catch vuoti.
Per le integrazioni con trasporto HTTP, la ricetta tratta un errore di trasporto e uno stato HTTP senza esito positivo come due casi distinti. Un client PSR-18 solleva un’eccezione client tipizzata solo quando la richiesta non può essere inviata. Una risposta 4xx o 5xx è un normale valore di ritorno che la ricetta esamina, non un’eccezione da intercettare.

3. Front-matter di riproducibilità

Ogni ricetta dichiara il grado di riproducibilità del proprio output, utilizzando il contratto di front-matter §5.1 applicato dallo schema dei contenuti del sito. I campi rilevanti sono:

reproducibility_profile — uno tra bitwise, structural o semantic. bitwise indica che i byte dell’output sono identici tra le esecuzioni a parità di input fissati. structural indica che la struttura del documento è identica, mentre i byte incidentali (timestamp, ordine degli oggetti) possono differire. semantic indica che il risultato renderizzato è equivalente senza una garanzia a livello di byte o di struttura. Una ricetta dichiara il profilo più forte che può garantire onestamente, non il profilo più forte esistente.
output_hash — quando il profilo è bitwise, contiene lo SHA-256 dell’output atteso, in modo che chi legge possa verificare il risultato documentato. Resta vuoto quando il profilo non supporta un hash stabile.
runnable_example — il percorso examples/… che produce l’output della ricetta e collega la pagina all’esempio basato sul codice sorgente in §1.
performance_budget — un limite facoltativo per il tempo effettivo e la memoria di picco della ricetta, affinché una ricetta che è anche un’affermazione sulle prestazioni resti delimitata e testabile.
compatibility — le versioni di PHP su cui la ricetta dichiara di funzionare. Le ricette utilizzano PHP 8.4 per impostazione predefinita; una ricetta che cita una funzionalità esclusiva di 8.4 elenca il backport nel proprio front-matter ed evidenzia la funzionalità nel blocco di codice.

Il profilo di riproducibilità corrisponde al contratto di riproducibilità §8.4. Chi legge lo utilizza per sapere se «l’output» indica byte esatti o un documento equivalente.

4. Il gate di pubblicazione

Ogni pagina di questo ricettario mantiene publish: false finché non supera il Writing Gate. L’impostazione predefinita è il diniego: il merge di una pagina non la pubblica; serve una decisione di gate esplicita registrata nel front-matter. Una ricetta le cui citazioni normative non hanno potuto essere fissate a causa di una reale interruzione del compliance-engine riporta inoltre un marcatore di citazione irrisolta. Resta publish: false finché la citazione non viene fissata di nuovo. Il protocollo di fallback per le interruzioni dell’infrastruttura RAG del repository governa tale marcatore; chi scrive ricette segue quel protocollo anziché inventare una citazione o eliminare l’affermazione.

5. L’aggregatore scrive i campi di provenienza

Non si scrivono a mano i quattro campi di provenienza del codice sorgente di cui è responsabile l’aggregatore: source_repo, source_ref, source_hash e manifest_hash. L’aggregatore li compila quando estrae la ricetta dal proprio repository sorgente, in modo che la pagina pubblicata registri esattamente quale revisione del repository l’ha prodotta. Se in uno qualsiasi di questi campi rimane un segnaposto, l’aggregatore lo sovrascrive; il segnaposto non raggiunge mai la pagina pubblicata.

Riepilogo

Una ricetta di questo ricettario è: codice basato sul sorgente e corredato di un test, un linguaggio per blocco, gestione esplicita degli errori per gli how-to di produzione, un profilo di riproducibilità onesto, impostazione predefinita publish: false fino al Writing Gate e provenienza inserita dall’aggregatore. Una pagina che soddisfa tutti e sei questi requisiti è una ricetta; una pagina che ne soddisfa meno è una bozza.

Vedere anche

Ricettario di integrazione — riferimento per il pacchetto e i vincoli fondamentali.
Scegliere un’integrazione — la matrice decisionale per caso d’uso.