Convenções de receitas

Toda receita executável no cookbook de integração segue o mesmo contrato. Esta página documenta esse contrato para que você saiba o que esperar de uma receita e o que quem a escreve deve fornecer. Ela é descritiva: registra a convenção. A aplicação dessa convenção fica no ferramental do repositório e na planilha de substituição de estilo, não aqui.

Cada integração armazena as receitas em docs/public/ no próprio repositório de origem, e o agregador as traz para este site. Essas convenções valem onde quer que uma receita esteja.

1. Os exemplos são código real, não trechos digitados à mão

O código de uma receita fica em um repositório. Não é um trecho digitado diretamente no texto.

Qualquer bloco de código PHP com mais de cinco linhas vem de um diretório examples/ no repositório correspondente ou de um diretório tests/Cookbook/.
O bloco declara a origem na string de informação do bloco cercado, por exemplo title="examples/standalone.php".
Um teste correspondente verifica que o exemplo ainda compila e produz a saída documentada, de modo que a página renderizada não pode divergir do código que exibe.

Esta convenção vem da planilha de substituição de estilo da documentação, §3.4 (“Os exemplos devem ser executáveis”). Uma receita que mostra código sem um exemplo ou teste que o respalde não atende à convenção.

2. Uma linguagem por bloco, com o tratamento de erros visível

Um bloco de código cercado contém exatamente uma linguagem, declarada explicitamente ( ```php, ```bash, ```yaml, ```json). Blocos cercados sem linguagem não são usados.
Uma receita marcada como guia prático pronto para produção mostra try / catch explicitamente, captura o tipo de exceção aplicável mais específico em vez do \Exception genérico e faz com que o bloco catch realize algo que o leitor possa copiar (registrar em log, relançar ou retornar um objeto de erro definido). Blocos catch vazios não são usados.
Em integrações com transporte por Hypertext Transfer Protocol (HTTP), a receita trata uma falha de transporte e um status HTTP sem sucesso como dois casos distintos. Um cliente PHP Standards Recommendation (PSR)-18 lança uma exceção de cliente tipada apenas quando a requisição não pode ser enviada. Uma resposta 4xx ou 5xx é um valor de retorno normal que a receita inspeciona, não uma exceção que ela captura.

3. Front-matter de reprodutibilidade

Cada receita declara o quanto sua saída é reproduzível. Ela usa o contrato de front-matter da §5.1 aplicado pelo schema de conteúdo do site. Os campos relevantes são:

reproducibility_profile — um de bitwise, structural ou semantic. bitwise significa que os bytes de saída são idênticos entre execuções, dadas as entradas fixadas. structural significa que a estrutura do documento é idêntica, embora bytes incidentais (carimbos de data/hora, ordem dos objetos) possam diferir. semantic significa que o resultado renderizado é equivalente, sem garantia de bytes ou de estrutura. Uma receita declara o perfil mais forte que pode sustentar honestamente, não o perfil mais forte disponível.
output_hash — quando o perfil é bitwise, o SHA-256 da saída esperada, para que o leitor possa verificar o resultado documentado. Vazio quando o perfil não suporta um hash estável.
runnable_example — o caminho examples/… que produz a saída da receita, vinculando a página ao exemplo respaldado pelo código-fonte na §1.
performance_budget — um limite opcional de tempo de relógio e de pico de memória para a receita, de modo que uma receita que também faz uma afirmação de desempenho permaneça limitada e testável.
compatibility — as versões de PHP em que a receita afirma rodar. As receitas têm como padrão o PHP 8.4; uma receita que nomeia um recurso exclusivo do 8.4 lista o backport em seu front-matter e destaca o recurso no bloco de código.

O perfil de reprodutibilidade é o contrato de reprodutibilidade da §8.4. Você o usa para saber se “a saída” significa bytes exatos ou um documento equivalente.

4. O portão de publicação

Toda página neste cookbook carrega publish: false até passar pelo Writing Gate. O padrão é negar a publicação: fazer merge de uma página não a publica; somente uma decisão explícita do portão registrada no front-matter faz isso. Uma receita cujas citações normativas não puderam ser fixadas por causa de uma indisponibilidade real do compliance-engine também carrega um marcador de citação não resolvida. Ela permanece publish: false até que a citação seja refixada. O protocolo de fallback para indisponibilidade de infraestrutura de retrieval-augmented generation (RAG) do repositório rege esse marcador; quem escreve a receita segue esse protocolo em vez de inventar uma citação ou descartar a afirmação.

5. O agregador escreve os campos de proveniência

Quem escreve uma receita não preenche manualmente os quatro campos de proveniência de origem que pertencem ao agregador: source_repo, source_ref, source_hash e manifest_hash. O agregador os preenche quando puxa a receita de seu repositório de origem, de modo que a página publicada registra exatamente qual revisão do repositório a produziu. Se um autor deixar um espaço reservado em qualquer um desses campos, o agregador o sobrescreve; o espaço reservado nunca chega à página publicada.

Resumo

Uma receita neste cookbook tem código respaldado pelo código-fonte com um teste, uma linguagem por bloco, tratamento de erros explícito para guias práticos de produção, um perfil de reprodutibilidade honesto, um padrão publish: false até o Writing Gate e proveniência injetada pelo agregador. Uma página que atende a todos os seis critérios é uma receita; uma página que atende a menos critérios é um rascunho.

Veja também

Cookbook de integração — a referência de pacotes e restrições do núcleo.
Escolha uma integração — a matriz de decisão por caso de uso.