Recipe-conventies

Elk uitvoerbaar recipe in het integratiecookbook volgt hetzelfde contract. Deze pagina beschrijft dat contract, zodat je weet wat je van een recipe kunt verwachten en wat de auteur van een recipe moet aanleveren. De pagina legt alleen de conventie vast. Afdwingen gebeurt via de repository-tooling en het stijloverschrijvingsblad, niet hier.

Elke integratie bewaart haar recipes onder docs/public/ in de eigen broncoderepository, en de aggregator haalt ze naar deze site. Deze conventies gelden ongeacht waar een recipe zich bevindt.

1. Voorbeelden zijn echte code, geen handmatig getypte fragmenten

De code van een recipe staat in een repository. Het is geen fragment dat handmatig in de tekst is getypt.

Elk PHP-codeblok dat langer is dan vijf regels, komt uit een examples/-map in de bijbehorende repository, of uit een tests/Cookbook/-map.
Het blok vermeldt zijn herkomst in de info-string van het afgebakende blok, bijvoorbeeld title="examples/standalone.php".
Een bijbehorende test bevestigt dat het voorbeeld nog steeds compileert en de gedocumenteerde uitvoer oplevert, zodat de weergegeven pagina niet kan afwijken van de code die ze toont.

Deze conventie komt uit het stijloverschrijvingsblad voor documentatie §3.4 (“Voorbeelden moeten uitvoerbaar zijn”). Een recipe dat code toont zonder onderliggend voorbeeld of test, voldoet niet aan de conventie.

2. Eén taal per blok, met zichtbare foutafhandeling

Een afgebakend codeblok bevat precies één taal, expliciet opgegeven ( ```php, ```bash, ```yaml, ```json). Kale afbakeningen worden niet gebruikt.
Een recipe dat is gemarkeerd als een productieklare how-to toont try / catch expliciet, vangt het meest specifieke toepasselijke uitzonderingstype af in plaats van het kale \Exception, en het catch-blok doet iets wat een lezer kan kopiëren (loggen, opnieuw werpen of een gedefinieerd foutobject retourneren). Lege catch-blokken worden niet gebruikt.
Voor integraties met Hypertext Transfer Protocol (HTTP)-transport behandelt het recipe een transportfout en een niet-succesvolle HTTP-status als twee afzonderlijke gevallen. Een client volgens PHP Standards Recommendation (PSR)-18 werpt alleen een getypeerde clientuitzondering wanneer de aanvraag niet kan worden verzonden. Een antwoord met 4xx of 5xx is een normale retourwaarde die het recipe inspecteert, geen uitzondering die het afvangt.

3. Front-matter voor reproduceerbaarheid

Elk recipe geeft aan hoe reproduceerbaar de uitvoer ervan is. Het gebruikt het front-matter-contract §5.1, dat door het contentschema van de site wordt afgedwongen. De relevante velden zijn:

reproducibility_profile — een van bitwise, structural of semantic. bitwise betekent dat de uitvoerbytes bij herhaalde uitvoeringen identiek zijn, gegeven de vastgezette invoer. structural betekent dat de documentstructuur identiek is, terwijl incidentele bytes (tijdstempels, objectvolgorde) kunnen verschillen. semantic betekent dat het weergegeven resultaat gelijkwaardig is, zonder garantie op byte- of structuurniveau. Een recipe vermeldt het sterkste profiel dat het eerlijk kan ondersteunen, niet het sterkste profiel dat beschikbaar is.
output_hash — wanneer het profiel bitwise is, de SHA-256 van de verwachte uitvoer, zodat een lezer het gedocumenteerde resultaat kan verifiëren. Het veld blijft leeg wanneer het profiel geen stabiele hash ondersteunt.
runnable_example — het examples/…-pad dat de uitvoer van het recipe produceert en de pagina koppelt aan het door broncode ondersteunde voorbeeld in §1.
performance_budget — een optionele bovengrens voor de kloktijd en het piekgeheugen van het recipe, zodat een recipe dat ook een prestatiebewering doet, begrensd en testbaar blijft.
compatibility — de PHP-versies waarop het recipe claimt te draaien. Recipes gaan standaard uit van PHP 8.4; als een recipe een functie noemt die alleen in 8.4 bestaat, vermeldt het de backport in de front-matter en wijst het die functie expliciet aan in het codeblok.

Het reproduceerbaarheidsprofiel is het reproduceerbaarheidscontract §8.4. Je gebruikt het om te bepalen of met “de uitvoer” exacte bytes of een gelijkwaardig document wordt bedoeld.

4. De publicatiepoort

Elke pagina in dit cookbook heeft publish: false totdat ze de Writing Gate passeert. Standaard wordt geweigerd: het samenvoegen van een pagina publiceert deze niet; alleen een expliciete poortbeslissing die in de front-matter is vastgelegd, doet dat. Een recipe waarvan de normatieve verwijzingen niet konden worden vastgezet vanwege een werkelijke storing van de compliance-engine, draagt ook een markering voor een onopgeloste verwijzing. Het blijft publish: false totdat de verwijzing opnieuw wordt vastgezet. Het terugvalprotocol in de repository voor infrastructuurstoringen van retrieval-augmented generation (RAG) beheert die markering; een recipe-auteur volgt dat protocol in plaats van een verwijzing te verzinnen of de bewering te laten vallen.

5. De aggregator schrijft de herkomstvelden

Een recipe-auteur vult de vier broncode-herkomstvelden die eigendom zijn van de aggregator niet handmatig in: source_repo, source_ref, source_hash en manifest_hash. De aggregator vult ze in wanneer deze het recipe uit de broncoderepository haalt, zodat de gepubliceerde pagina precies vastlegt uit welke repository-revisie ze is voortgekomen. Als een auteur in een van deze velden een tijdelijke aanduiding laat staan, overschrijft de aggregator deze; de tijdelijke aanduiding bereikt nooit de gepubliceerde pagina.

Samenvatting

Een recipe in dit cookbook bevat code die door broncode wordt ondersteund en getest is, gebruikt één taal per blok, heeft expliciete foutafhandeling voor productie-how-to’s, noemt een eerlijk reproduceerbaarheidsprofiel, blijft standaard op publish: false tot aan de Writing Gate en krijgt herkomstvelden van de aggregator. Een pagina die aan alle zes voldoet, is een recipe; een pagina die aan minder punten voldoet, is een concept.

Zie ook

Integratiecookbook — de referentie voor pakketten en kernbeperkingen.
Kies een integratie — de beslissingsmatrix per use-case.