Recipe conventions

Recipe conventions

Every runnable recipe in the integration cookbook follows the same contract. This page documents that contract so you know what to expect from a recipe and what a recipe author must provide. It is descriptive: it records the convention. Enforcement lives in the repository tooling and the style override sheet, not here.

Each integration stores its recipes under docs/public/ in its own source repository, and the aggregator pulls them into this site. These conventions apply wherever a recipe lives.

1. Samples are real code, not hand-typed snippets

A recipe’s code exists in a repository. It is not a snippet typed into the prose.

• Any PHP code block longer than five lines comes from an examples/ directory in the corresponding repository, or from a tests/Cookbook/ directory.
• The block declares its origin in the fenced-block info string, for example title="examples/standalone.php".
• A corresponding test asserts that the example still compiles and produces the documented output, so the rendered page cannot drift from the code it shows.

This convention comes from the documentation style override sheet §3.4 (“Samples must be runnable”). A recipe that shows code without a backing example or test does not meet the convention.

2. One language per block, with error handling visible

• A fenced code block contains exactly one language, declared explicitly ( ```php, ```bash, ```yaml, ```json). Bare fences are not used.
• A recipe marked as a production-ready how-to shows try / catch explicitly, catches the most specific applicable exception type rather than bare \Exception, and the catch block does something a reader can copy (log, rethrow, or return a defined error object). Empty catch blocks are not used.
• For Hypertext Transfer Protocol (HTTP)-transport integrations, the recipe treats a transport failure and a non-success HTTP status as two separate cases. A PHP Standards Recommendation (PSR)-18 client raises a typed client exception only when the request cannot be sent. A 4xx or 5xx response is a normal return value the recipe inspects, not an exception it catches.

3. Reproducibility front-matter

Each recipe declares how reproducible its output is. It uses the §5.1 front-matter contract enforced by the site’s content schema. The relevant fields are:

• reproducibility_profile — one of bitwise, structural, or semantic. bitwise means the output bytes are identical across runs given the pinned inputs. structural means the document structure is identical while incidental bytes (timestamps, object order) may differ. semantic means the rendered result is equivalent, without a byte or structure guarantee. A recipe states the strongest profile it can honestly support, not the strongest profile available.
• output_hash — when the profile is bitwise, the SHA-256 of the expected output, so a reader can verify the documented result. Empty when the profile does not support a stable hash.
• runnable_example — the examples/… path that produces the recipe’s output, tying the page to the source-backed sample in §1.
• performance_budget — an optional wall-clock and peak-memory cap for the recipe, so a recipe that also makes a performance claim stays bounded and testable.
• compatibility — the PHP versions the recipe claims to run on. Recipes default to PHP 8.4; a recipe that names an 8.4-only feature lists the backport in its front-matter and calls the feature out in the code block.

The reproducibility profile is the §8.4 reproducibility contract. You use it to tell whether “the output” means exact bytes or an equivalent document.

4. The publish gate

Every page in this cookbook carries publish: false until it clears the Writing Gate. The default is deny: merging a page does not publish it; only an explicit gate decision recorded in front-matter does. A recipe whose normative citations could not be pinned because of a genuine compliance-engine outage also carries an unresolved-citation marker. It stays publish: false until the citation re-pins. The repository’s retrieval-augmented generation (RAG) infra-outage fallback protocol governs that marker; a recipe author follows that protocol instead of inventing a citation or dropping the claim.

5. The aggregator writes the provenance fields

A recipe author does not hand-write the four source-provenance fields owned by the aggregator: source_repo, source_ref, source_hash, and manifest_hash. The aggregator fills them in when it pulls the recipe from its source repository, so the published page records exactly which repository revision produced it. If an author leaves a placeholder in any of these fields, the aggregator overwrites it; the placeholder never reaches the published page.

Summary

A recipe in this cookbook has source-backed code with a test, one language per block, explicit error handling for production how-tos, an honest reproducibility profile, a publish: false default until the Writing Gate, and aggregator-injected provenance. A page that meets all six is a recipe; a page that meets fewer is a draft.

See also

• Integration cookbook — the package and core-constraint reference.
• Choose an integration — the use-case decision matrix.