Recipe-Konventionen

Jedes lauffähige Recipe im Integrations-Cookbook folgt demselben Vertrag. Diese Seite dokumentiert ihn, damit Leser wissen, was sie von einem Recipe erwarten können, und Autoren wissen, was ein Recipe erfüllen muss. Sie ist beschreibend: Sie hält die Konvention fest. Durchgesetzt wird sie im Repository-Tooling und im Style-Override-Sheet, nicht hier.

Das jeweilige Quell-Repository jeder Integration hält ihre Recipes unter docs/public/ vor; der Aggregator übernimmt sie in diese Site. Die folgenden Konventionen gelten unabhängig davon, wo ein Recipe liegt.

1. Beispiele sind echter Code, keine von Hand getippten Snippets

Der Code in einem Recipe ist echter Code, der in einem Repository existiert, kein direkt in den Fließtext getipptes Snippet.

Jeder PHP-Codeblock mit mehr als fünf Zeilen stammt aus einem examples/-Verzeichnis im zugehörigen Repository oder aus einem tests/Cookbook/-Verzeichnis.
Der Block gibt seine Herkunft im Info-String des Code-Fences an, zum Beispiel title="examples/standalone.php".
Ein zugehöriger Test stellt sicher, dass das Beispiel weiterhin kompiliert und die dokumentierte Ausgabe erzeugt, sodass die gerenderte Seite nicht von dem Code abdriften kann, den sie zeigt.

Diese Konvention ist §3.4 des Style-Override-Sheets der Dokumentation („Beispiele müssen lauffähig sein“). Ein Recipe, das Code ohne hinterlegtes Beispiel oder hinterlegten Test zeigt, erfüllt die Konvention nicht.

2. Eine Sprache pro Block, mit sichtbarer Fehlerbehandlung

Ein Code-Fence enthält genau eine Sprache, die explizit deklariert ist ( ```php, ```bash, ```yaml, ```json). Fences ohne Sprachangabe werden nicht verwendet.
Ein Recipe, das als produktionsreifes How-to gekennzeichnet ist, zeigt try / catch explizit, fängt den spezifischsten anwendbaren Exception-Typ statt eines nackten \Exception und enthält im catch-Block eine Handlung, die ein Leser übernehmen kann (loggen, erneut werfen oder ein definiertes Fehlerobjekt zurückgeben). Leere catch-Blöcke werden nicht verwendet.
Bei Integrationen über HTTP-Transport behandelt das Recipe einen Transportfehler und einen HTTP-Status ohne Erfolg als zwei getrennte Fälle. Ein PSR-18-Client wirft eine typisierte Client-Exception nur dann, wenn die Anfrage nicht gesendet werden kann. Eine 4xx- oder 5xx-Antwort ist ein normaler Rückgabewert, den das Recipe prüft, und keine Exception, die es fängt.

3. Reproduzierbarkeits-Frontmatter

Jedes Recipe deklariert über den Frontmatter-Vertrag aus §5.1, den das Content-Schema der Site durchsetzt, wie reproduzierbar seine Ausgabe ist. Die relevanten Felder:

reproducibility_profile — einer der Werte bitwise, structural oder semantic. bitwise bedeutet, dass die Ausgabe-Bytes über alle Läufe hinweg identisch sind, sofern die Eingaben gepinnt sind. structural bedeutet, dass die Dokumentstruktur identisch ist, während beiläufige Bytes (Zeitstempel, Objektreihenfolge) abweichen können. semantic bedeutet, dass das gerenderte Ergebnis gleichwertig ist, ohne Byte- oder Struktur-Garantie. Ein Recipe nennt das stärkste Profil, das es ehrlich einhalten kann, nicht das stärkste Profil, das es gibt.
output_hash — wenn das Profil bitwise ist, der SHA-256 der erwarteten Ausgabe, damit Leser das dokumentierte Ergebnis verifizieren können. Leer, wenn das Profil keinen stabilen Hash unterstützt.
runnable_example — der examples/…-Pfad, der die Ausgabe des Recipes erzeugt und die Seite mit dem quellgestützten Beispiel aus §1 verbindet.
performance_budget — eine optionale Obergrenze für Laufzeit (Wall-Clock) und Spitzenspeicher des Recipes, damit ein Recipe, das zugleich eine Performanceaussage ist, begrenzt und testbar bleibt.
compatibility — die PHP-Versionen, auf denen das Recipe laut eigener Angabe läuft. Recipes setzen standardmäßig PHP 8.4 voraus; ein Recipe, das ein nur in 8.4 vorhandenes Feature benennt, führt den Backport in seinem Frontmatter auf und weist im Codeblock auf das Feature hin.

Das Reproduzierbarkeitsprofil ist der Reproduzierbarkeitsvertrag aus §8.4. Leser nutzen es, um zu wissen, ob „die Ausgabe“ exakte Bytes oder ein gleichwertiges Dokument meint.

4. Das Publish-Gate

Jede Seite in diesem Cookbook trägt publish: false, bis sie das Writing-Gate passiert hat. Die Voreinstellung ist Verweigern: Das Mergen einer Seite veröffentlicht sie nicht; das geschieht nur durch eine explizite, im Frontmatter festgehaltene Gate-Entscheidung. Ein Recipe, dessen normative Zitate wegen eines echten Ausfalls der Compliance-Engine nicht gepinnt werden konnten, trägt zusätzlich einen Marker für ungelöste Zitate. Die Seite bleibt publish: false, bis das Zitat erneut gepinnt ist. Das RAG-Infrastruktur-Ausfall-Fallback-Protokoll des Repositorys regelt diesen Marker; ein Recipe-Autor hält sich an dieses Protokoll, statt ein Zitat zu erfinden oder die Aussage fallen zu lassen.

5. Der Aggregator schreibt die Provenance-Felder

Ein Recipe-Autor füllt die vier Quell-Provenance-Felder, die dem Aggregator gehören, nicht von Hand aus: source_repo, source_ref, source_hash und manifest_hash. Der Aggregator füllt sie aus, wenn er das Recipe aus seinem Quell-Repository übernimmt, sodass die veröffentlichte Seite genau festhält, aus welcher Repository-Revision sie erzeugt wurde. Lässt ein Autor in einem dieser Felder einen Platzhalter stehen, überschreibt der Aggregator ihn; der Platzhalter gelangt nie auf die veröffentlichte Seite.

Zusammenfassung

Ein Recipe in diesem Cookbook besteht aus: quellgestütztem Code mit einem Test, einer Sprache pro Block, expliziter Fehlerbehandlung für produktive How-tos, einem ehrlichen Reproduzierbarkeitsprofil, einer publish: false-Voreinstellung bis zum Writing-Gate und vom Aggregator eingespielter Provenance. Eine Seite, die alle sechs Punkte erfüllt, ist ein Recipe; eine Seite, die weniger davon erfüllt, ist ein Entwurf.

Siehe auch

Integrations-Cookbook — die Referenz zu Paketen und Core-Constraints.
Eine Integration auswählen — die Entscheidungsmatrix nach Anwendungsfall.