SPI kararlılığı kuralları

Bir bakışta

NextPDF’nin hizmet sağlayıcı arayüzü, Semantic Versioning kurallarını izler. Her genel sözleşme bir @stability etiketiyle bir geriye dönük uyumluluk sözü taşır. Hangi sözleşmelere bağımlı olabileceğinize karar verirken bu kuralları kullanın.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Hizmet sağlayıcı arayüzü, NextPDF\Contracts ve NextPDF\Event ad alanlarındaki genel sözleşmeleri kapsar. Bir tür, yalnızca kaynak PHPDoc’u bir @stability etiketi taşıyorsa arayüzün parçasıdır. Sınırı etiket belirler. Etiketi olmayan bir tür, PHP tarafından public olarak sunulsa bile dahilidir.

NextPDF, Semantic Versioning 2.0.0 kurallarını izler. Bir stable sözleşmedeki kırıcı değişiklik, ana sürümün artırılmasını gerektirir. Yeni bir sözleşme veya kırıcı olmayan bir ekleme, ikincil sürümü artırır. Bir hata düzeltmesi, yama sürümünü artırır.

@stability etiketi

Her sözleşme üç kararlılık değerinden birini bildirir:

Etiket	Anlamı	Değişiklik kuralı
stable	Üretime hazırdır. Bağımlı olmak güvenlidir.	İkincil veya yama sürümünde kırıcı değişiklik yapılmaz. Yeni yöntemler yalnızca varsayılan bir davranışla veya yeni bir sözleşmede eklenir.
experimental	Kullanılabilir, ancak henüz dondurulmamıştır.	Arayüz, önce kullanımdan kaldırma bildirimi verilerek bir ikincil sürümde değişebilir.
deprecated	Kaldırılmak üzere planlanmıştır.	Sözleşme, yerine geçeni ve kaldırılacağı sürümü belirtir.

NextPDF, sözleşme başına verilen her sözü oluşturulan sözleşmeler haritasına kaydeder ve bu haritayı her sürümde kaynaktan yeniden oluşturur. Söz metni, ilgili sözleşme için geçerli kuralın tamamını verir. Sözleşmenin kaynak PHPDoc’unu tek doğruluk kaynağı olarak ele alın.

Geriye dönük uyumluluk sözü sınıfları

Sözleşmeler haritası, her sözü dört sınıftan birine kaydeder:

1. Arayüz sözü. “İkincil veya yama sürümünde kırıcı değişiklik yapılmaz. Yeni yöntemler yalnızca varsayılan bir uygulamayla eklenir.” Çoğu stable arayüz için geçerlidir; FontRegistryInterface, SignerInterface, HsmSignerInterface ve HtmlSecurityPolicyInterface bunlara dahildir.
2. Numaralandırma sözü. “Hiçbir durum kaldırılmaz. İkincil bir sürümde yeni durumlar eklenebilir.” stable numaralandırmalar için geçerlidir; örneğin Alignment, Orientation ve OutputDestination.
3. Dondurulmuş değer nesnesi sözü. “Yapıcı imzası ve genel özellikler dondurulur. Yeni yöntemler eklenebilir.” TextPreprocessResult, TextSegment gibi değer nesneleri ve bunlara bağlı olay yükleri için geçerlidir.
4. Deneysel söz. “Arayüz, kullanımdan kaldırma bildirimiyle birlikte ikincil bir sürümde değişebilir.” experimental sözleşmeler için geçerlidir; örneğin DeferredSignerInterface, TimestampProviderInterface, CursorInterface ve StreamingWriterInterface.

Bir final sınıf — örneğin EventDispatcher veya ListenerProvider — genel yöntem imzalarını dondurur. Bir final sınıfı genişletmeniz gerekiyorsa kompozisyon kullanın. Alt sınıf olarak türetmeyin.

Deneysel akış sözleşmeleri

CursorInterface ve StreamingWriterInterface, experimental durumundadır (3.1.0 sürümünden beri). NextPDF, her iki sözleşme için de nihai, test edilmiş motor uygulamaları sağlar; uygulama sınıfları dahilidir ve genel yüzeyin parçası değildir. Akış davranışını genel experimental sözleşme üzerinden kullanırsınız. Çoğu durumda sözleşmeyi kendiniz uygulamazsınız.

Sözleşme experimental olduğundan, imzası önce kullanımdan kaldırma bildirimi verilerek bir ikincil sürümde değişebilir (deneysel söz). Üretimde bu sözleşmeye bağımlı olmadan önce sıkıca sabitleyin veya kendi adaptörünüzün arkasına alın. Akış sözleşmesini dondurulmuş bir nokta olarak değil, kararlılığa doğru ilerleyen bir genişletme noktası olarak ele alın.

API yüzeyi

Bu sayfada çalışma zamanı uygulama programlama arayüzü (API) bulunmaz. İlgili yüzey, her genel sözleşmedeki @stability PHPDoc etiketi ile sözleşme başına verilen sözü bir araya getiren, yeniden oluşturulmuş sözleşmeler haritasıdır.

Kod örneği — hızlı başlangıç

Bir sözleşmeye bağımlı olmadan önce kararlılığını kaynağından okuyun.

<?php

declare(strict_types=1);

use ReflectionClass;

$doc = (new ReflectionClass(\NextPDF\Contracts\FontRegistryInterface::class))
    ->getDocComment();

// Look for the "@stability stable" line in the contract PHPDoc.
\assert(\is_string($doc) && \str_contains($doc, '@stability stable'));

Kod örneği — üretim

Bir Composer sürüm kısıtlaması, bir stable sözleşme için kırıcı değişikliklerin gerçekleşebileceği ana sürümü sabitler.

{
    "require": {
        "nextpdf/core": "^3.0"
    }
}

Şunu kullanın: ^3.0 — herhangi bir stable sözleşmede kırıcı değişiklik almadan ikincil ve yama sürümlerini alırsınız. Bir experimental sözleşmeye bağımlı olduğunuzda daha sıkı sabitleyin; çünkü bir experimental sözleşme bir ikincil sürümde değişebilir.

Uç durumlar & tuzaklar

• Görünürlük değil, etiket. public olarak işaretlenmiş bir PHP yöntemi, onu bildiren tür bir @stability etiketi taşımadıkça hizmet sağlayıcı arayüzünün parçası değildir.
• Deneysel kayma. Bir experimental sözleşme bir ikincil sürümde değişebilir. Sıkıca sabitleyin veya kendi adaptörünüzün arkasına alın. Bu, birlikte gelen uygulamaları olsa bile akış sözleşmeleri için geçerlidir.
• Yeni varsayılan yöntemler. Bir stable arayüz, varsayılan davranışa sahip bir yöntem kazanabilir. Kendi uygulamanızın davranışı açık kalsın diye yükseltme yaptığınızda yeni yöntemi uygulayın.
• Sürüm eşliği. NextPDF Pro ve NextPDF Enterprise aynı kuralları izler. Core’da hedeflediğiniz bir sözleşme, aynı sözleşmenin bir Premium uygulamasına karşı geçerli kalır.

Kullanımdan kaldırma yaşam döngüsü

Bir sözleşme, tanımlı bir yaşam döngüsü izler:

1. İşaretleme. Sahibi, kaynak PHPDoc’unda @stability deprecated olarak ayarlar ve yerine geçeni ile kaldırılacağı sürümü kaydeder.
2. Bildirim. Kullanımdan kaldırma, işaretlemenin yapıldığı sürümün değişiklik günlüğünde duyurulur.
3. Örtüşme. Kullanımdan kaldırılan sözleşme ve yerine geçeni en az bir ikincil sürüm boyunca bir arada bulunur.
4. Kaldırma. Sözleşme, belirtilen ana sürümde kaldırılır. Kaldırma asla bir ikincil veya yama sürümünde gerçekleşmez.

Bir sözleşme deprecated olarak işaretlenir işaretlenmez bir yükseltme planlayın. Yerine geçeni her zaman belirtilir.

Performans

Bu sayfa politika tanımlar. Çalışma zamanı maliyeti yoktur.

Güvenlik notları

İmzalama sözleşmeleri stable durumundadır ve arayüz sözüne uyar. Bir imzalama sözleşmesindeki yeni bir yöntem yalnızca varsayılan bir davranışla veya yeni bir sözleşmede gelir; bu nedenle donanım destekli bir uygulama bir ikincil yükseltmede bozulmaz. Bir ana yükseltmeden önce değişiklik günlüğünü inceleyin; çünkü bir ana sürüm bir stable sözleşmeyi değiştirebilir.

Uygunluk

Bu sürümleme kuralları, Semantic Versioning 2.0.0 ile uyumludur. Değişiklik günlüğü oluşturma, Conventional Commits 1.0.0 kurallarını izler.

Ticari bağlam

NextPDF Pro ve NextPDF Enterprise, Core ile aynı hizmet sağlayıcı arayüzü kararlılık kurallarını izler. Core’da hedeflediğiniz bir sözleşme, o sözleşmenin Premium uygulamasına karşı geçerli kalır; böylece genişletme kodunuz sürümler arasında taşınabilir olur.

Ayrıca bakınız

• Genişletme yazımına genel bakış
• Özel yazı tipleri
• Eylem tetikleyicileri ve olay dinleyicileri
• KMS sağlayıcı sözleşmesi

İlgili sözleşmeler ve modüller

• Sözleşmeler modülü başvurusu — oluşturulan sözleşmeler haritası ve sözleşme başına verilen söz metni.
• Akış sözleşmeleri başvurusu — experimental akış sözleşmeleri ve birlikte gelen uygulamaları.
• İmzalama sözleşmeleri başvurusu — aynı kurallara tabi stable ve experimental imzalama sözleşmeleri.
• Genişletme yazımına genel bakış — her @stability etiketinin pratikte ne anlama geldiği.
• Eylem tetikleyicileri ve olay dinleyicileri — bu kuralların yönettiği final gönderici ve deneysel yükler.

Sözlük, kararlılık etiketi ve geriye dönük uyumluluk sözü terimlerini tanımlar. Standart tanımlar için yayımlanmış sözlüğe bakın.