Zasady stabilności SPI

W skrócie

Interfejs dostawcy usług NextPDF stosuje wersjonowanie semantyczne. Każdy publiczny kontrakt ma znacznik @stability oraz obietnicę zgodności wstecznej. Te zasady pomagają zdecydować, na których kontraktach można polegać.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Interfejs dostawcy usług obejmuje publiczne kontrakty w przestrzeniach nazw NextPDF\Contracts oraz NextPDF\Event. Typ wchodzi w skład interfejsu tylko wtedy, gdy jego źródłowy PHPDoc zawiera znacznik @stability. Ten znacznik wyznacza granicę. Typ bez tego znacznika jest wewnętrzny, nawet jeśli PHP udostępnia go jako public.

NextPDF stosuje wersjonowanie semantyczne 2.0.0. Zmiana łamiąca zgodność w kontrakcie stable wymaga zwiększenia wersji głównej. Nowy kontrakt lub rozszerzenie nienaruszające zgodności zwiększa wersję pomocniczą. Poprawka błędu zwiększa wersję poprawkową.

Znacznik @stability

Każdy kontrakt deklaruje jedną z trzech wartości stabilności:

Znacznik	Znaczenie	Reguła zmiany
stable	Gotowy do środowiska produkcyjnego. Można na nim bezpiecznie polegać.	Brak zmian łamiących zgodność w wydaniu pomocniczym lub poprawkowym. Nowe metody są dodawane wyłącznie z domyślnym zachowaniem lub w nowym kontrakcie.
experimental	Nadaje się do użycia, ale nie jest jeszcze zamrożony.	Interfejs może się zmienić w wydaniu pomocniczym, po wcześniejszym powiadomieniu o wycofaniu.
deprecated	Zaplanowany do usunięcia.	Kontrakt wskazuje zamiennik oraz wersję, w której nastąpi usunięcie.

NextPDF zapisuje obietnicę każdego kontraktu w wygenerowanej mapie kontraktów i regeneruje tę mapę ze źródła przy każdym wydaniu. Tekst obietnicy określa dokładną regułę dla danego kontraktu. Traktuj źródłowy PHPDoc kontraktu jako jedyne źródło prawdy.

Klasy obietnic zgodności wstecznej

Mapa kontraktów zapisuje każdą obietnicę w jednej z czterech klas:

1. Obietnica interfejsu. „Brak zmian łamiących zgodność w wydaniu pomocniczym ani poprawkowym. Nowe metody tylko z domyślną implementacją.” Dotyczy większości interfejsów stable, w tym FontRegistryInterface, SignerInterface, HsmSignerInterface oraz HtmlSecurityPolicyInterface.
2. Obietnica typu wyliczeniowego. „Brak usuwania przypadków. W wersji pomocniczej można dodawać nowe przypadki.” Dotyczy typów wyliczeniowych stable, takich jak Alignment, Orientation oraz OutputDestination.
3. Obietnica zamrożonego obiektu wartości. „Sygnatura konstruktora i właściwości publiczne są zamrożone. Można dodawać nowe metody.” Dotyczy obiektów wartości, takich jak TextPreprocessResult, TextSegment oraz powiązanych z nimi ładunków zdarzeń.
4. Obietnica eksperymentalna. „Interfejs może się zmienić w wersji pomocniczej, po wcześniejszym powiadomieniu o wycofaniu.” Dotyczy kontraktów experimental, takich jak DeferredSignerInterface, TimestampProviderInterface, CursorInterface oraz StreamingWriterInterface.

Klasa oznaczona jako final, taka jak EventDispatcher lub ListenerProvider, zamraża sygnatury swoich metod publicznych. Aby rozszerzyć klasę final, użyj kompozycji. Nie twórz jej podklasy.

Eksperymentalne kontrakty strumieniowe

CursorInterface i StreamingWriterInterface mają status experimental (od wersji 3.1.0). NextPDF dostarcza finalne, przetestowane implementacje silnika dla obu kontraktów; klasy implementacji są wewnętrzne i nie stanowią części powierzchni publicznej. Z zachowania strumieniowego korzystasz przez publiczny kontrakt experimental. W większości przypadków nie implementuje się tego kontraktu samodzielnie.

Ponieważ kontrakt ma status experimental, jego sygnatura może się zmienić w wydaniu pomocniczym, po wcześniejszym powiadomieniu o wycofaniu (obietnica eksperymentalna). Przypnij wersję ściślej lub opakuj kontrakt we własny adapter, zanim zaczniesz na nim polegać w środowisku produkcyjnym. Traktuj kontrakt strumieniowy jako stabilizujący się punkt rozszerzenia, nie jako punkt zamrożony.

Powierzchnia API

Ta strona nie definiuje API czasu wykonywania. Istotną powierzchnią API jest znacznik PHPDoc @stability w każdym publicznym kontrakcie oraz regenerowana mapa kontraktów, która agreguje obietnicę dla każdego kontraktu.

Przykład kodu — szybki start

Odczytaj stabilność kontraktu ze źródła, zanim zaczniesz na nim polegać.

<?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'));

Przykład kodu — środowisko produkcyjne

Ograniczenie wersji w Composerze przypina wersję główną, poza którą zachodzą zmiany łamiące zgodność dla kontraktu stable.

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

Użyj ^3.0, aby otrzymywać wydania pomocnicze i poprawkowe bez zmian łamiących zgodność w jakimkolwiek kontrakcie stable. Przypnij wersję ściślej, gdy polegasz na kontrakcie experimental, ponieważ kontrakt experimental może się zmienić w wydaniu pomocniczym.

Przypadki brzegowe i pułapki

• Znacznik, a nie widoczność. Metoda PHP oznaczona jako public nie jest częścią interfejsu dostawcy usług, jeśli typ, w którym jest zadeklarowana, nie zawiera znacznika @stability.
• Dryf eksperymentalny. Kontrakt experimental może się zmienić w wydaniu pomocniczym. Przypnij wersję ściślej lub opakuj kontrakt we własny adapter. Dotyczy to kontraktów strumieniowych, mimo że dostarczono dla nich implementacje.
• Nowe metody domyślne. Interfejs stable może zyskać metodę z domyślnym zachowaniem. Podczas aktualizacji zaimplementuj nową metodę, aby własna implementacja pozostała jawna.
• Równoważność edycji. NextPDF Pro i NextPDF Enterprise stosują te same zasady. Kontrakt, na którym opierasz się w edycji Core, pozostaje ważny względem implementacji Premium tego samego kontraktu.

Cykl życia wycofywania

Kontrakt przechodzi przez zdefiniowany cykl życia:

1. Oznaczenie. Właściciel ustawia @stability deprecated w źródłowym PHPDoc oraz zapisuje zamiennik i wersję, w której nastąpi usunięcie.
2. Powiadomienie. Wycofanie ogłasza się w dzienniku zmian wydania, które je oznacza.
3. Nakładanie się. Wycofany kontrakt i jego zamiennik współistnieją przez co najmniej jedno wydanie pomocnicze.
4. Usunięcie. Kontrakt zostaje usunięty w podanym wydaniu głównym. Usunięcie nigdy nie następuje w wydaniu pomocniczym lub poprawkowym.

Zaplanuj aktualizację, gdy tylko kontrakt zostanie oznaczony jako deprecated. Zamiennik jest zawsze wskazany.

Wydajność

Ta strona definiuje politykę. Nie wiąże się z żadnym kosztem w czasie wykonywania.

Uwagi dotyczące bezpieczeństwa

Kontrakty podpisywania mają status stable i podlegają obietnicy interfejsu. Nowa metoda w kontrakcie podpisywania pojawia się wyłącznie z domyślnym zachowaniem lub w nowym kontrakcie, więc implementacja oparta na sprzęcie nie przestaje działać po aktualizacji pomocniczej. Przed aktualizacją do nowej wersji głównej przejrzyj dziennik zmian, ponieważ wersja główna może zmienić kontrakt stable.

Zgodność

Te zasady wersjonowania są zgodne z wersjonowaniem semantycznym 2.0.0. Generowanie dziennika zmian jest zgodne z Conventional Commits 1.0.0.

Kontekst komercyjny

NextPDF Pro i NextPDF Enterprise stosują te same zasady stabilności interfejsu dostawcy usług co edycja Core. Kontrakt, na którym opierasz się w edycji Core, pozostaje ważny względem implementacji Premium tego kontraktu, dzięki czemu kod rozszerzenia jest przenośny między edycjami.

Zobacz także

• Przegląd tworzenia rozszerzeń
• Niestandardowe czcionki
• Wyzwalacze akcji i nasłuchiwacze zdarzeń
• Kontrakt dostawcy KMS

Powiązane kontrakty i moduły

• Dokumentacja modułu kontraktów — wygenerowana mapa kontraktów i tekst obietnicy dla każdego kontraktu.
• Dokumentacja kontraktów strumieniowych — kontrakty strumieniowe experimental oraz ich dostarczane implementacje.
• Dokumentacja kontraktów podpisywania — kontrakty podpisywania stable oraz experimental podlegające tym samym zasadom.
• Przegląd tworzenia rozszerzeń — co w praktyce oznacza każdy znacznik @stability.
• Wyzwalacze akcji i nasłuchiwacze zdarzeń — dyspozytor final oraz eksperymentalne ładunki, które podlegają tym zasadom.

Glosariusz definiuje pojęcia znacznik stabilności oraz obietnica zgodności wstecznej. Kanoniczne definicje znajdziesz w opublikowanym glosariuszu.