Соглашения для рецептов

Каждый выполняемый рецепт в сборнике интеграций следует одному и тому же контракту. Эта страница описывает этот контракт, чтобы вы понимали, чего ожидать от рецепта и что должен предоставить его автор. Она носит описательный характер: фиксирует соглашение. Принудительное соблюдение обеспечивают инструменты репозитория и таблица переопределений стиля, а не эта страница.

Каждая интеграция хранит свои рецепты в каталоге docs/public/ собственного исходного репозитория, а агрегатор переносит их на этот сайт. Эти соглашения действуют независимо от расположения рецепта.

1. Примеры — это настоящий код, а не фрагменты, набранные вручную

Код рецепта находится в репозитории. Это не фрагмент, набранный вручную в тексте.

Любой блок кода PHP длиннее пяти строк берётся из каталога examples/ в соответствующем репозитории или из каталога tests/Cookbook/.
Блок указывает своё происхождение в информационной строке огороженного блока, например title="examples/standalone.php".
Соответствующий тест подтверждает, что пример по-прежнему компилируется и выдаёт задокументированный результат, поэтому отображаемая страница не может разойтись с кодом, который показывает.

Это соглашение следует из таблицы переопределений стиля документации, §3.4 (“Примеры должны быть исполняемыми”). Рецепт, который показывает код без подтверждающего примера или теста, этому соглашению не соответствует.

2. Один язык на блок и явная обработка ошибок

Блок кода в ограждении содержит ровно один язык, объявленный явно ( ```php, ```bash, ```yaml, ```json). Ограждения без указания языка не используются.
Рецепт, помеченный как руководство, готовое к продакшену, явно показывает try / catch, перехватывает наиболее конкретный применимый тип исключения, а не “голый” \Exception, а блок catch выполняет действие, которое читатель может скопировать (записать в журнал, повторно выбросить или вернуть определённый объект ошибки). Пустые блоки catch не используются.
Для интеграций с транспортом через протокол передачи гипертекста (HTTP) рецепт рассматривает сбой транспорта и неуспешный статус HTTP как два отдельных случая. Клиент, соответствующий рекомендации стандартов PHP (PSR)-18, выбрасывает типизированное клиентское исключение только тогда, когда запрос не удаётся отправить. Ответ 4xx или 5xx — это обычное возвращаемое значение: рецепт проверяет его, а не перехватывает как исключение.

3. Фронтматтер воспроизводимости

Каждый рецепт объявляет, насколько воспроизводим его результат. Для этого он использует контракт фронтматтера §5.1, соблюдение которого обеспечивает схема контента сайта. Соответствующие поля:

reproducibility_profile — одно из значений bitwise, structural или semantic. bitwise означает, что байты вывода идентичны во всех запусках при зафиксированных входных данных. structural означает, что структура документа идентична, хотя несущественные байты (метки времени, порядок объектов) могут различаться. semantic означает, что отображаемый результат эквивалентен, но байты или структура не гарантируются. Рецепт указывает самый строгий профиль, который может честно поддержать, а не самый строгий доступный профиль.
output_hash — когда профиль равен bitwise, это SHA-256 ожидаемого вывода, чтобы читатель мог проверить задокументированный результат. Поле пустое, если профиль не поддерживает стабильный хеш.
runnable_example — путь examples/…, который создаёт результат рецепта и связывает страницу с примером из §1, подкреплённым исходным кодом.
performance_budget — необязательное ограничение по реальному времени и пиковой памяти для рецепта, чтобы рецепт, где также заявлена производительность, оставался ограниченным по ресурсам и проверяемым.
compatibility — версии PHP, для которых рецепт заявляет работоспособность. По умолчанию рецепты рассчитаны на PHP 8.4; рецепт, который называет возможность, доступную только в 8.4, указывает бэкпорт в своём фронтматтере и выделяет эту возможность в блоке кода.

Профиль воспроизводимости — это контракт воспроизводимости §8.4. По нему вы определяете, означает ли “вывод” точные байты или эквивалентный документ.

4. Шлюз публикации

Каждая страница в этом сборнике содержит publish: false, пока не пройдёт шлюз контроля текстов (Writing Gate). По умолчанию публикация запрещена: слияние страницы не публикует её; это делает только явное решение шлюза, записанное во фронтматтере. Рецепт, нормативные ссылки которого не удалось закрепить из-за реального сбоя движка соответствия (compliance-engine), также получает маркер неразрешённой ссылки. Он остаётся publish: false до тех пор, пока ссылка не будет закреплена повторно. Этим маркером управляет протокол отказоустойчивости репозитория при сбое инфраструктуры генерации с дополненной выборкой (RAG); автор рецепта следует этому протоколу, а не выдумывает ссылку и не отбрасывает утверждение.

5. Агрегатор записывает поля происхождения

Автор рецепта не заполняет вручную четыре поля происхождения исходного кода, за которые отвечает агрегатор: source_repo, source_ref, source_hash и manifest_hash. Агрегатор заполняет их при извлечении рецепта из исходного репозитория, поэтому опубликованная страница фиксирует, из какой именно ревизии репозитория она получена. Если автор оставляет в любом из этих полей заполнитель, агрегатор перезаписывает его; заполнитель никогда не попадает на опубликованную страницу.

Сводка

Рецепт в этом сборнике содержит код из исходного репозитория, подтверждённый тестом, один язык на блок, явную обработку ошибок для готовых к продакшену руководств, честный профиль воспроизводимости, значение publish: false по умолчанию до прохождения шлюза контроля текстов и поля происхождения, добавленные агрегатором. Страница, которая соблюдает все шесть требований, является рецептом; страница, которая соблюдает меньше требований, является черновиком.

См. также

Сборник интеграций — справочник по пакетам и ограничениям ядра.
Выбор интеграции — матрица решений для сценариев использования.