Conventions des recipes

Chaque recipe exécutable du Cookbook d’intégration suit le même contrat. Cette page le documente afin que le lecteur sache ce qu’il peut attendre d’une recipe, et l’auteur ce qu’une recipe doit respecter. Elle est descriptive : elle consigne la convention. L’application de la règle relève de l’outillage du dépôt et de la feuille de surcharge de style, pas d’ici.

Le dépôt source propre à chaque intégration héberge ses recipes sous docs/public/, et l’agrégateur les importe vers ce site. Les conventions ci-dessous s’appliquent à toute recipe, quel que soit son emplacement.

1. Les exemples sont du vrai code, pas des extraits tapés à la main

Le code d’une recipe est du vrai code présent dans un dépôt, pas un extrait saisi dans la prose.

Tout bloc de code PHP de plus de cinq lignes provient d’un répertoire examples/ du dépôt correspondant, ou d’un répertoire tests/Cookbook/.
Le bloc déclare son origine dans la chaîne d’information de sa clôture de code, par exemple title="examples/standalone.php".
Un test correspondant vérifie que l’exemple compile toujours et produit encore la sortie documentée, de sorte que la page rendue ne peut pas diverger du code qu’elle montre.

Cette convention correspond au §3.4 de la feuille de surcharge de style de la documentation (« Samples must be runnable »). Une recipe qui présente du code sans exemple ni test à l’appui ne respecte pas la convention.

2. Un seul langage par bloc, avec une gestion des erreurs visible

Une clôture de code contient exactement un langage, déclaré explicitement ( ```php, ```bash, ```yaml, ```json). Les clôtures sans langage ne sont pas utilisées.
Une recipe marquée comme guide pratique prêt pour la production montre try / catch explicitement, attrape le type d’exception applicable le plus spécifique plutôt qu’un \Exception nu, et le bloc catch fait quelque chose qu’un lecteur peut copier (journaliser, relancer ou renvoyer un objet d’erreur défini). Les blocs catch vides ne sont pas utilisés.
Pour les intégrations à transport HTTP, la recipe traite une défaillance de transport et un statut HTTP non réussi comme deux cas distincts. Un client PSR-18 ne lève une exception client typée que lorsque la requête ne peut pas être envoyée. Une réponse 4xx ou 5xx est une valeur de retour normale que la recipe inspecte, pas une exception qu’elle attrape.

3. Front-matter de reproductibilité

Chaque recipe déclare à quel point sa sortie est reproductible, au moyen du contrat de front-matter du §5.1 imposé par le schéma de contenu du site. Les champs concernés :

reproducibility_profile — l’une des valeurs bitwise, structural ou semantic. bitwise signifie que les octets de sortie sont identiques d’une exécution à l’autre, pour des entrées épinglées. structural signifie que la structure du document est identique tandis que des octets accessoires (horodatages, ordre des objets) peuvent différer. semantic signifie que le résultat rendu est équivalent, sans garantie sur les octets ni sur la structure. Une recipe énonce le profil le plus fort qu’elle peut honnêtement tenir, pas le profil le plus fort qui existe.
output_hash — lorsque le profil est bitwise, le SHA-256 de la sortie attendue, pour qu’un lecteur puisse vérifier le résultat documenté. Vide lorsque le profil ne prend pas en charge un hash stable.
runnable_example — le chemin examples/… qui produit la sortie de la recipe, reliant la page à l’exemple adossé à une source du §1.
performance_budget — un plafond optionnel de temps réel et de pic mémoire pour la recipe, pour qu’une recipe qui est aussi une affirmation de performance reste bornée et testable.
compatibility — les versions de PHP sur lesquelles la recipe affirme s’exécuter. Les recipes ciblent PHP 8.4 par défaut ; une recipe qui nomme une fonctionnalité réservée à 8.4 liste le backport dans sa front-matter et signale la fonctionnalité dans le bloc de code.

Le profil de reproductibilité est le contrat de reproductibilité du §8.4. Le lecteur s’en sert pour savoir si « la sortie » désigne des octets exacts ou un document équivalent.

4. Le publish gate

Chaque page de ce Cookbook porte publish: false jusqu’à ce qu’elle franchisse le Writing Gate. Le réglage par défaut est le refus : fusionner une page ne la publie pas ; seule une décision de gate explicite consignée dans la front-matter le fait. Une recipe dont les citations normatives n’ont pas pu être épinglées à cause d’une véritable panne du compliance-engine porte en plus un marqueur de citation non résolue. Elle reste publish: false jusqu’à ce que la citation soit réépinglée. Le protocole de repli en cas de panne d’infrastructure RAG du dépôt régit ce marqueur ; un auteur de recipe suit ce protocole plutôt que d’inventer une citation ou de supprimer l’affirmation.

5. L’agrégateur écrit les champs de provenance

Un auteur de recipe ne renseigne pas à la main les quatre champs de provenance de source dont l’agrégateur est propriétaire : source_repo, source_ref, source_hash et manifest_hash. L’agrégateur les remplit lorsqu’il importe la recipe depuis son dépôt source, de sorte que la page publiée consigne exactement quelle révision du dépôt l’a produite. Si un auteur laisse un espace réservé dans l’un de ces champs, l’agrégateur l’écrase ; l’espace réservé n’atteint jamais la page publiée.

Résumé

Une recipe de ce Cookbook, c’est : du code adossé à une source avec un test, un seul langage par bloc, une gestion explicite des erreurs pour les guides pratiques de production, un profil de reproductibilité honnête, un publish: false par défaut jusqu’au Writing Gate, et une provenance injectée par l’agrégateur. Une page qui satisfait les six critères est une recipe ; une page qui en satisfait moins est un brouillon.

Voir aussi

Cookbook d’intégration — la référence des packages et des contraintes du cœur.
Choisir une intégration — la matrice de décision par cas d’usage.