Convenciones para recipes

Cada recipe ejecutable del cookbook de integraciones sigue el mismo contrato. Esta página lo documenta para que quien lee sepa qué esperar de una recipe y quien escribe sepa qué debe cumplir. Es una referencia descriptiva: registra la convención. La aplicación de las reglas reside en las herramientas del repositorio y en la hoja de overrides de estilo, no aquí.

El repositorio de código fuente de cada integración guarda sus propias recipes en docs/public/, y el aggregator las incorpora a este sitio. Las convenciones siguientes se aplican sin importar dónde viva la recipe.

1. Los ejemplos son código real, no fragmentos escritos a mano

El código de una recipe es código real que existe en un repositorio; no es un fragmento escrito dentro de la prosa.

Todo bloque de código PHP de más de cinco líneas procede de un directorio examples/ del repositorio correspondiente o de un directorio tests/Cookbook/.
El bloque declara su origen en la cadena de información de la valla de código, por ejemplo title="examples/standalone.php".
Una prueba correspondiente comprueba que el ejemplo todavía compila y sigue produciendo la salida documentada, de modo que la página renderizada no pueda divergir del código que muestra.

Esta convención corresponde a la §3.4 de la hoja de overrides de estilo de la documentación («Los ejemplos deben ser ejecutables»). Una recipe que muestra código sin un ejemplo o una prueba que lo respalde no cumple la convención.

2. Un lenguaje por bloque, con el manejo de errores visible

Un bloque de código vallado contiene exactamente un lenguaje, declarado de forma explícita ( ```php, ```bash, ```yaml, ```json). No se usan vallas sin lenguaje.
Una recipe marcada como how-to listo para producción muestra try / catch de forma explícita, captura el tipo de excepción aplicable más específico en lugar de \Exception a secas, y el bloque catch hace algo que quien lee puede copiar (registrar, relanzar o devolver un objeto de error definido). No se usan bloques catch vacíos.
Para integraciones de transporte HTTP, la recipe trata un fallo de transporte y un estado HTTP que no sea de éxito como dos casos separados. Un cliente PSR-18 lanza una excepción de cliente tipada solo cuando la solicitud no se puede enviar. Una respuesta 4xx o 5xx es un valor de retorno normal que la recipe inspecciona, no una excepción que la recipe capture.

3. Front-matter de reproducibilidad

Cada recipe declara el grado de reproducibilidad de su salida mediante el contrato de front-matter de la §5.1 que aplica el esquema de contenido del sitio. Los campos relevantes:

reproducibility_profile — uno de bitwise, structural o semantic. bitwise significa que los bytes de salida son idénticos entre ejecuciones con las entradas fijadas. structural significa que la estructura del documento es idéntica, aunque los bytes incidentales (marcas de tiempo, orden de objetos) pueden diferir. semantic significa que el resultado renderizado es equivalente, sin garantía de bytes ni de estructura. Una recipe declara el perfil más fuerte que puede sostener con honestidad, no el perfil más fuerte que existe.
output_hash — cuando el perfil es bitwise, el SHA-256 de la salida esperada, para que quien lee pueda verificar el resultado documentado. Vacío cuando el perfil no admite un hash estable.
runnable_example — la ruta examples/… que produce la salida de la recipe y vincula la página con el ejemplo respaldado por código fuente de la §1.
performance_budget — un límite opcional de tiempo de reloj y memoria pico para la recipe, de modo que una recipe que también es una afirmación de rendimiento se mantenga acotada y comprobable.
compatibility — las versiones de PHP en las que la recipe afirma que se ejecuta. Las recipes usan PHP 8.4 de forma predeterminada; una recipe que nombra una característica exclusiva de 8.4 lista el backport en su front-matter y resalta la característica en el bloque de código.

El perfil de reproducibilidad es el contrato de reproducibilidad de la §8.4. Quien lee lo usa para saber si «la salida» significa bytes exactos o un documento equivalente.

4. El publish gate

Toda página de este cookbook mantiene publish: false hasta que pasa el Writing Gate. El valor predeterminado es denegar: fusionar una página no la publica; solo la publica una decisión explícita del gate registrada en el front-matter. Una recipe cuyas citas normativas no se pudieron fijar a causa de una interrupción genuina del compliance-engine lleva además un marcador de cita sin resolver. Permanece publish: false hasta que la cita se vuelva a fijar. El protocolo de respaldo ante interrupciones de la infraestructura RAG del repositorio gobierna ese marcador; quien escribe recipes sigue ese protocolo en lugar de inventar una cita o descartar la afirmación.

5. El aggregator escribe los campos de procedencia

Quien escribe recipes no completa a mano los cuatro campos de procedencia de la fuente que pertenecen al aggregator: source_repo, source_ref, source_hash y manifest_hash. El aggregator los completa cuando trae la recipe desde su repositorio de código fuente, de modo que la página publicada registra exactamente qué revisión del repositorio la produjo. Si un autor deja un marcador de posición en cualquiera de estos campos, el aggregator lo sobrescribe; el marcador de posición nunca llega a la página publicada.

Resumen

Una recipe de este cookbook reúne: código respaldado por código fuente y por una prueba, un lenguaje por bloque, manejo de errores explícito para los how-to de producción, un perfil de reproducibilidad honesto, un publish: false predeterminado hasta el Writing Gate, y procedencia inyectada por el aggregator. Una página que cumple las seis condiciones es una recipe; una página que cumple menos es un borrador.

Véase también

Cookbook de integraciones — la referencia de paquetes y restricciones del core.
Elegir una integración — la matriz de decisión por caso de uso.