Tarif kuralları

Entegrasyon Cookbook’undaki çalıştırılabilir her tarif aynı sözleşmeye uyar. Bu sayfa, bir tariften ne beklemeniz ve bir tarif yazarının neleri sağlaması gerektiğini bilmeniz için bu sözleşmeyi belgeler. Betimleyicidir: kuralı kayıt altına alır. Zorunlu kılma burada değil, depo araçlarında ve stil geçersiz kılma sayfasında yer alır.

Her entegrasyon, tariflerini kendi kaynak deposundaki docs/public/ dizininde saklar; toplayıcı da bunları bu siteye çeker. Bu kurallar, tarif nerede bulunursa bulunsun geçerlidir.

1. Örnekler gerçek koddur, elle yazılmış parçacıklar değil

Bir tarifteki kod bir depoda bulunur. Metin içine elle yazılmış bir parçacık değildir.

Beş satırdan uzun her PHP kod bloğu, ilgili depodaki bir examples/ dizininden veya bir tests/Cookbook/ dizininden gelir.
Blok, kaynağını kod çitinin bilgi dizesinde bildirir; örneğin title="examples/standalone.php".
İlgili bir test, o örneğin hâlâ derlendiğini ve belgelenen çıktıyı ürettiğini doğrular; böylece oluşturulan sayfa, gösterdiği koddan sapamaz.

Bu kural, belge stili geçersiz kılma sayfası §3.4’ten (“Örnekler çalıştırılabilir olmalıdır”) gelir. Destekleyici bir örneği veya testi olmadan kod gösteren bir tarif bu kuralı karşılamaz.

2. Blok başına tek dil, hata işleme görünürdür

Çitlenmiş bir kod bloğu, açıkça bildirilmiş tam olarak tek bir dil içerir ( ```php, ```bash, ```yaml, ```json). Çıplak çit kullanılmaz.
Üretime hazır bir uygulama kılavuzu olarak işaretlenmiş bir tarif, try / catch ifadesini açıkça gösterir, çıplak \Exception yerine uygulanabilen en özel istisna türünü yakalar ve catch bloğu, okuyucunun kopyalayabileceği bir işlem yapar (günlüğe kaydetme, yeniden fırlatma veya tanımlı bir hata nesnesi döndürme). Boş catch blokları kullanılmaz.
Hypertext Transfer Protocol (HTTP) taşıma katmanını kullanan entegrasyonlarda tarif, taşıma hatası ile başarısız HTTP durumunu iki ayrı durum olarak ele alır. Bir PHP Standards Recommendation (PSR)-18 istemcisi, yalnızca istek gönderilemediğinde tiplendirilmiş bir istemci istisnası fırlatır. Bir 4xx veya 5xx yanıtı, tarifin yakaladığı bir istisna değildir; tarifin incelediği normal bir dönüş değeridir.

3. Yeniden üretilebilirlik ön bilgisi

Her tarif, çıktısının ne ölçüde yeniden üretilebilir olduğunu bildirir. Sitenin içerik şemasının zorunlu kıldığı §5.1 ön bilgi sözleşmesini kullanır. İlgili alanlar şunlardır:

reproducibility_profile — bitwise, structural veya semantic değerlerinden biri. bitwise, sabitlenmiş girdiler verildiğinde çıktı baytlarının çalıştırmalar boyunca aynı kalacağı anlamına gelir. structural, belge yapısının aynı olduğu, buna karşın rastlantısal baytların (zaman damgaları, nesne sırası) farklılık gösterebileceği anlamına gelir. semantic, oluşturulan sonucun bayt veya yapı garantisi olmadan eşdeğer olduğu anlamına gelir. Bir tarif, mevcut en güçlü profili değil; dürüstçe destekleyebileceği en güçlü profili belirtir.
output_hash — profil bitwise olduğunda, beklenen çıktının SHA-256 değeri; böylece bir okuyucu belgelenen sonucu doğrulayabilir. Profil kararlı bir karma değeri desteklemediğinde boş bırakılır.
runnable_example — tarifin çıktısını üreten examples/… yolu; sayfayı §1’deki kaynak destekli örneğe bağlar.
performance_budget — tarif için isteğe bağlı bir duvar saati ve tepe bellek üst sınırı; böylece performans iddiası da taşıyan bir tarif sınırlı ve test edilebilir kalır.
compatibility — tarifin üzerinde çalıştığını iddia ettiği PHP sürümleri. Tarifler varsayılan olarak PHP 8.4 kullanır; yalnızca 8.4’e özgü bir özelliği adlandıran bir tarif, geri uyarlamayı ön bilgisinde listeler ve özelliği kod bloğunda belirtir.

Yeniden üretilebilirlik profili, §8.4 yeniden üretilebilirlik sözleşmesini ifade eder. Bunu, “çıktı” ifadesinin tam baytları mı yoksa eşdeğer bir belgeyi mi belirttiğini anlamak için kullanırsınız.

4. Yayımlama kapısı

Bu Cookbook’taki her sayfa, Yazım Kapısı’nı geçene kadar publish: false taşır. Varsayılan davranış reddetmektir: bir sayfanın birleştirilmesi onu yayımlamaz; yalnızca ön bilgide kayıt altına alınmış açık bir kapı kararı yayımlanmasını sağlar. Gerçek bir uyumluluk motoru kesintisi nedeniyle düzenleyici alıntıları sabitlenemeyen bir tarif, ayrıca çözülmemiş alıntı işaretçisi taşır. Alıntı yeniden sabitlenene kadar publish: false olarak kalır. Bu işaretçi, deponun erişimle artırılmış üretim (RAG) altyapısı kesintileri için yedek protokolüyle yönetilir; bir tarif yazarı, bir alıntı uydurmak veya iddiayı bırakmak yerine bu protokolü izler.

5. Köken alanlarını toplayıcı yazar

Bir tarif yazarı, toplayıcının sahip olduğu dört kaynak köken alanını elle yazmaz: source_repo, source_ref, source_hash ve manifest_hash. Toplayıcı, tarifi kaynak deposundan çekerken bunları doldurur; böylece yayımlanan sayfa, tam olarak hangi depo revizyonundan üretildiğini kayıt altına alır. Bir yazar, bu alanların herhangi birinde bir yer tutucu bırakırsa toplayıcı onun üzerine yazar; yer tutucu hiçbir zaman yayımlanan sayfaya ulaşmaz.

Özet

Bu Cookbook’taki bir tarif; testi olan kaynak destekli koda, blok başına tek dile, üretim uygulama kılavuzları için açık hata işlemeye, dürüst bir yeniden üretilebilirlik profiline, Yazım Kapısı’na kadar geçerli olan publish: false varsayılanına ve toplayıcı tarafından eklenen kökene sahiptir. Altısının tamamını karşılayan bir sayfa bir tariftir; daha azını karşılayan bir sayfa ise taslaktır.

Ayrıca bakınız

Entegrasyon Cookbook — paket ve çekirdek kısıtları için başvuru.
Bir entegrasyon seçin — kullanım senaryosu karar matrisi.