Konwencje przepisów

Każdy uruchamialny przepis w książce kucharskiej integracji podlega temu samemu kontraktowi. Ta strona opisuje ten kontrakt, aby było jasne, czego oczekiwać od przepisu i co musi dostarczyć jego autor. Ma charakter opisowy: utrwala konwencję. Jej egzekwowanie odbywa się w narzędziach repozytorium oraz w arkuszu nadpisań stylu, a nie tutaj.

Każda integracja przechowuje swoje przepisy w katalogu docs/public/ we własnym repozytorium źródłowym, a agregator pobiera je do tej witryny. Te konwencje obowiązują niezależnie od tego, gdzie znajduje się przepis.

1. Próbki to prawdziwy kod, a nie ręcznie wpisane fragmenty

Kod przepisu znajduje się w repozytorium. Nie jest fragmentem wpisanym bezpośrednio w treść.

Każdy blok kodu PHP dłuższy niż pięć wierszy pochodzi z katalogu examples/ w odpowiednim repozytorium albo z katalogu tests/Cookbook/.
Blok deklaruje swoje pochodzenie w łańcuchu informacyjnym ogrodzonego bloku, na przykład title="examples/standalone.php".
Odpowiadający mu test sprawdza, że przykład nadal się kompiluje i wytwarza udokumentowany wynik, dzięki czemu wyrenderowana strona nie może odbiegać od kodu, który prezentuje.

Ta konwencja pochodzi z arkusza nadpisań stylu dokumentacji §3.4 („Próbki muszą być uruchamialne”). Przepis, który pokazuje kod bez odpowiadającego mu przykładu lub testu, nie spełnia tej konwencji.

2. Jeden język na blok, z widoczną obsługą błędów

Ogrodzony blok kodu zawiera dokładnie jeden język, zadeklarowany jawnie ( ```php, ```bash, ```yaml, ```json). Nie używa się ogrodzeń bez deklaracji języka.
Przepis oznaczony jako poradnik gotowy do produkcji pokazuje jawnie try / catch, przechwytuje najbardziej szczegółowy typ wyjątku mający zastosowanie zamiast samego \Exception, a blok catch wykonuje działanie, które czytelnik może skopiować (zapisuje do dziennika, ponownie zgłasza wyjątek lub zwraca zdefiniowany obiekt błędu). Nie używa się pustych bloków catch.
W przypadku integracji opartych na transporcie Hypertext Transfer Protocol (HTTP) przepis traktuje awarię transportu oraz niepomyślny status HTTP jako dwa odrębne przypadki. Klient zgodny z PHP Standards Recommendation (PSR)-18 zgłasza typowany wyjątek klienta wyłącznie wtedy, gdy żądania nie można wysłać. Odpowiedź 4xx lub 5xx jest normalną wartością zwracaną, którą przepis sprawdza, a nie wyjątkiem, który przechwytuje.

3. Front-matter odtwarzalności

Każdy przepis deklaruje, w jakim stopniu jego wynik jest odtwarzalny. Korzysta z kontraktu front-matter §5.1 egzekwowanego przez schemat treści witryny. Istotne pola to:

reproducibility_profile — jedna z wartości: bitwise, structural lub semantic. bitwise oznacza, że bajty wyniku są identyczne w kolejnych uruchomieniach przy ustalonych danych wejściowych. structural oznacza, że struktura dokumentu jest identyczna, choć bajty związane z elementami ubocznymi (znaczniki czasu, kolejność obiektów) mogą się różnić. semantic oznacza, że wyrenderowany rezultat jest równoważny, bez gwarancji co do bajtów lub struktury. Przepis podaje najsilniejszy profil, który może rzetelnie zapewnić, a nie najsilniejszy dostępny profil.
output_hash — gdy profilem jest bitwise, suma SHA-256 oczekiwanego wyniku, dzięki czemu czytelnik może zweryfikować udokumentowany rezultat. Pozostaje puste, gdy profil nie obsługuje stabilnej sumy kontrolnej.
runnable_example — ścieżka examples/…, która wytwarza wynik przepisu, wiążąc stronę z próbką opartą na źródle w §1.
performance_budget — opcjonalny limit czasu rzeczywistego i szczytowego zużycia pamięci dla przepisu, dzięki czemu przepis, który zawiera również deklarację wydajnościową, pozostaje ograniczony i testowalny.
compatibility — wersje PHP, dla których przepis deklaruje działanie. Przepisy domyślnie zakładają PHP 8.4; przepis, który wymienia funkcję dostępną wyłącznie w 8.4, podaje backport w swoim front-matter i wskazuje tę funkcję w bloku kodu.

Profil odtwarzalności to kontrakt odtwarzalności §8.4. Służy on do określenia, czy „wynik” oznacza dokładne bajty, czy równoważny dokument.

4. Bramka publikacji

Każda strona w tej książce kucharskiej zawiera publish: false, dopóki nie przejdzie Bramki Pisania. Wartością domyślną jest odmowa: scalenie strony nie publikuje jej; robi to wyłącznie jawna decyzja bramki zapisana we front-matter. Przepis, którego cytatów normatywnych nie udało się ustalić z powodu rzeczywistej awarii silnika zgodności, zawiera również znacznik nierozwiązanego cytatu. Pozostaje w stanie publish: false, dopóki cytat nie zostanie ponownie ustalony. Znacznik ten obsługuje protokół awaryjny repozytorium na wypadek awarii infrastruktury retrieval-augmented generation (RAG); autor przepisu stosuje ten protokół zamiast wymyślać cytat lub porzucać twierdzenie.

5. Agregator zapisuje pola pochodzenia

Autor przepisu nie wpisuje ręcznie czterech pól pochodzenia źródła, które należą do agregatora: source_repo, source_ref, source_hash oraz manifest_hash. Agregator wypełnia je, gdy pobiera przepis z jego repozytorium źródłowego, dzięki czemu opublikowana strona dokładnie wskazuje, która rewizja repozytorium ją wytworzyła. Jeśli autor pozostawi symbol zastępczy w którymkolwiek z tych pól, agregator go nadpisuje; symbol zastępczy nigdy nie trafia na opublikowaną stronę.

Podsumowanie

Przepis w tej książce kucharskiej ma kod oparty na źródle i objęty testem, jeden język na blok, jawną obsługę błędów w poradnikach produkcyjnych, uczciwy profil odtwarzalności, domyślną wartość publish: false do czasu Bramki Pisania oraz pochodzenie wstrzyknięte przez agregator. Strona, która spełnia wszystkie sześć warunków, jest przepisem; strona, która spełnia ich mniej, jest szkicem.

Zobacz także

Książka kucharska integracji — materiał referencyjny dotyczący pakietów i ograniczeń rdzenia.
Wybór integracji — macierz decyzyjna według przypadków użycia.