Konvensi resep

Setiap resep yang dapat dijalankan dalam cookbook integrasi mengikuti kontrak yang sama. Halaman ini mendokumentasikan kontrak tersebut sehingga Anda tahu apa yang dapat diharapkan dari sebuah resep dan apa yang harus disediakan oleh penulis resep. Halaman ini bersifat deskriptif: isinya mencatat konvensi tersebut. Penegakannya dilakukan oleh perkakas repositori dan lembar penggantian gaya, bukan di sini.

Setiap integrasi menyimpan resepnya di bawah docs/public/ dalam repositori sumbernya sendiri, dan agregator menarik resep tersebut ke situs ini. Konvensi ini berlaku di mana pun sebuah resep berada.

1. Contoh adalah kode nyata, bukan cuplikan yang diketik manual

Kode untuk sebuah resep berada di dalam repositori. Kode tersebut bukan cuplikan yang diketik langsung ke dalam prosa.

Setiap blok kode PHP yang panjangnya lebih dari lima baris berasal dari direktori examples/ di repositori terkait, atau dari direktori tests/Cookbook/.
Blok tersebut menyatakan asalnya melalui info string pada blok berpagar, misalnya title="examples/standalone.php".
Pengujian terkait memastikan bahwa contoh tersebut tetap dapat dikompilasi dan menghasilkan keluaran yang terdokumentasi, sehingga halaman yang dirender tidak dapat menyimpang dari kode yang ditampilkannya.

Konvensi ini bersumber dari lembar penggantian gaya dokumentasi §3.4 (“Contoh harus dapat dijalankan”). Resep yang menampilkan kode tanpa contoh atau pengujian pendukung tidak memenuhi konvensi ini.

2. Satu bahasa per blok, dengan penanganan kesalahan yang terlihat

Blok kode berpagar berisi tepat satu bahasa, yang dinyatakan secara eksplisit ( ```php, ```bash, ```yaml, ```json). Pagar tanpa penanda bahasa tidak digunakan.
Resep yang ditandai sebagai panduan praktis siap-produksi menampilkan try / catch secara eksplisit, menangkap tipe exception paling spesifik yang berlaku alih-alih \Exception polos, dan mengisi blok catch dengan tindakan yang dapat disalin pembaca (mencatat log, melempar ulang, atau mengembalikan objek kesalahan yang terdefinisi). Blok catch kosong tidak digunakan.
Untuk integrasi yang menggunakan transport Hypertext Transfer Protocol (HTTP), resep memperlakukan kegagalan transport dan status HTTP yang tidak berhasil sebagai dua kasus terpisah. Klien PHP Standards Recommendation (PSR)-18 hanya melemparkan exception klien bertipe ketika permintaan tidak dapat dikirim. Respons 4xx atau 5xx adalah nilai kembalian normal yang diperiksa oleh resep, bukan exception yang ditangkapnya.

3. Front-matter reproduksibilitas

Setiap resep menyatakan sejauh mana keluarannya dapat direproduksi. Resep menggunakan kontrak front-matter §5.1 yang ditegakkan oleh skema konten situs. Field yang relevan adalah:

reproducibility_profile — salah satu dari bitwise, structural, atau semantic. bitwise berarti byte keluaran identik di setiap eksekusi dengan masukan yang dipatok. structural berarti struktur dokumen identik, sementara byte insidental (stempel waktu, urutan objek) dapat berbeda. semantic berarti hasil yang dirender setara, tanpa jaminan byte atau struktur. Sebuah resep menyatakan profil terkuat yang dapat didukungnya secara jujur, bukan profil terkuat yang tersedia.
output_hash — ketika profilnya bitwise, berisi SHA-256 dari keluaran yang diharapkan, sehingga pembaca dapat memverifikasi hasil yang terdokumentasi. Kosong ketika profil tidak mendukung hash yang stabil.
runnable_example — jalur examples/… yang menghasilkan keluaran resep dan mengaitkan halaman dengan contoh yang didukung sumber di §1.
performance_budget — batas opsional untuk waktu jam-dinding dan memori puncak resep, sehingga resep yang juga membuat klaim kinerja tetap dibatasi dan dapat diuji.
compatibility — versi PHP yang diklaim dapat menjalankan resep. Resep secara baku menggunakan PHP 8.4; resep yang menyebut fitur khusus 8.4 mencantumkan backport-nya dalam front-matter dan menyorot fitur tersebut di blok kode.

Profil reproduksibilitas adalah kontrak reproduksibilitas §8.4. Anda menggunakannya untuk mengetahui apakah “keluaran” berarti byte yang persis sama atau dokumen yang setara.

4. Gerbang publikasi

Setiap halaman dalam cookbook ini membawa publish: false hingga lolos Gerbang Penulisan. Standarnya adalah tolak: menggabungkan sebuah halaman tidak menerbitkannya; hanya keputusan gerbang eksplisit yang dicatat dalam front-matter yang menerbitkannya. Resep yang sitasi normatifnya tidak dapat dipatok karena gangguan nyata pada compliance-engine juga membawa penanda sitasi-belum-terselesaikan. Halaman tersebut tetap publish: false hingga sitasi dipatok ulang. Protokol fallback untuk gangguan infrastruktur retrieval-augmented generation (RAG) milik repositori mengatur penanda tersebut; penulis resep mengikuti protokol itu alih-alih mengarang sitasi atau menghapus klaim.

5. Agregator menulis field provenans

Penulis resep tidak menulis manual keempat field provenans-sumber milik agregator: source_repo, source_ref, source_hash, dan manifest_hash. Agregator mengisinya saat menarik resep dari repositori sumbernya, sehingga halaman yang diterbitkan mencatat dengan tepat revisi repositori yang menghasilkannya. Jika penulis meninggalkan placeholder di salah satu field ini, agregator menimpanya; placeholder tersebut tidak pernah sampai ke halaman yang diterbitkan.

Ringkasan

Sebuah resep dalam cookbook ini memiliki kode yang didukung sumber beserta pengujian, satu bahasa per blok, penanganan kesalahan eksplisit untuk panduan praktis produksi, profil reproduksibilitas yang jujur, standar publish: false hingga Gerbang Penulisan, dan provenans yang disuntikkan oleh agregator. Halaman yang memenuhi keenamnya adalah resep; halaman yang belum memenuhi semuanya adalah draf.

Lihat juga

Buku resep integrasi — referensi paket dan batasan inti.
Memilih integrasi — matriks keputusan kasus penggunaan.