SPI-Stabilitätsregeln

Auf einen Blick

Das Service-Provider-Interface von NextPDF folgt Semantic Versioning. Jeder öffentliche Vertrag trägt ein @stability-Tag und ein Abwärtskompatibilitäts-Versprechen. Diese Seite legt die Regeln fest, damit Sie entscheiden können, worauf Sie sich verlassen.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Das Service-Provider-Interface umfasst die öffentlichen Verträge in den Namespaces NextPDF\Contracts und NextPDF\Event. Ein Typ ist nur dann Teil des Interface, wenn sein PHPDoc in der Quelle ein @stability-Tag trägt. Dieses Tag bildet die Grenze. Ein Typ ohne dieses Tag ist intern, selbst wenn er in PHP technisch public ist.

NextPDF folgt Semantic Versioning 2.0.0. Eine Breaking Change an einem stable-Vertrag erhöht die Major-Version. Ein neuer Vertrag oder eine nicht brechende Ergänzung erhöht die Minor-Version. Ein Bugfix erhöht die Patch-Version.

Das @stability-Tag

Jeder Vertrag deklariert einen von drei Stabilitätswerten:

Tag	Bedeutung	Änderungsregel
`stable`	Produktionsreif. Darauf können Sie sich verlassen.	Keine Breaking Change in einem Minor- oder Patch-Release. Neue Methoden werden nur mit einem Standardverhalten oder an einem neuen Vertrag hinzugefügt.
`experimental`	Nutzbar, aber noch nicht eingefroren.	Das Interface kann sich in einem Minor-Release ändern, vorher mit einem Deprecation-Hinweis.
`deprecated`	Zur Entfernung vorgesehen.	Der Vertrag nennt den Ersatz und die Entfernungs-Version.

Das Versprechen pro Vertrag wird in der generierten Contracts-Map festgehalten und bei jedem Release aus der Quelle neu generiert. Der Versprechenstext nennt die genaue Regel für diesen Vertrag. Betrachten Sie das PHPDoc der Vertragsquelle als einzige Quelle der Wahrheit.

Klassen des Abwärtskompatibilitäts-Versprechens

Die Contracts-Map hält das Versprechen fest. Versprechen fallen in vier Klassen:

Interface-Versprechen. „Keine Breaking Change in einem Minor- oder Patch-Release. Neue Methoden nur mit einer Standardimplementierung.“ Gilt für die meisten stable-Interfaces, darunter FontRegistryInterface, SignerInterface, HsmSignerInterface und HtmlSecurityPolicyInterface.
Enum-Versprechen. „Keine Entfernung von Cases. Neue Cases dürfen in einer Minor-Version hinzukommen.“ Gilt für stable-Enums wie Alignment, Orientation und OutputDestination.
Versprechen für eingefrorene Value-Objects. „Konstruktor-Signatur und öffentliche Properties sind eingefroren. Neue Methoden dürfen hinzukommen.“ Gilt für Value-Objects wie TextPreprocessResult, TextSegment und die daran gebundenen Event-Payloads.
Experimental-Versprechen. „Das Interface kann sich in einer Minor-Version mit einem Deprecation-Hinweis ändern.“ Gilt für experimental-Verträge wie DeferredSignerInterface, TimestampProviderInterface, CursorInterface und StreamingWriterInterface.

Eine final-Klasse wie EventDispatcher oder ListenerProvider friert ihre öffentlichen Methodensignaturen ein. Erweitern Sie eine final-Klasse per Komposition. Leiten Sie sie nicht ab.

Experimentelle Streaming-Verträge

CursorInterface und StreamingWriterInterface sind experimental (seit 3.1.0). NextPDF liefert eine finale, getestete Engine-Implementierung beider Verträge; die Implementierungsklassen sind intern und nicht Teil der öffentlichen Oberfläche. Sie nutzen das Streaming-Verhalten über den öffentlichen experimental-Vertrag. Im Regelfall implementieren Sie den Vertrag nicht selbst.

Da der Vertrag experimental ist, kann sich seine Signatur in einem Minor-Release ändern, vorher mit einem Deprecation-Hinweis (das Experimental-Versprechen). Pinnen Sie eng oder kapseln Sie ihn hinter einem eigenen Adapter, bevor Sie sich in Produktion darauf verlassen. Behandeln Sie den Streaming-Vertrag als sich stabilisierenden Erweiterungspunkt, nicht als eingefrorenen Vertrag.

API-Oberfläche

Diese Seite definiert keine Laufzeit-API. Die relevante Oberfläche ist das @stability-PHPDoc-Tag an jedem öffentlichen Vertrag sowie die neu generierte Contracts-Map, die das Versprechen pro Vertrag aggregiert.

Codebeispiel – Schnellstart

Lesen Sie die Stabilität eines Vertrags aus seiner Quelle, bevor Sie sich darauf verlassen.

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

Codebeispiel – Produktion

Ein Composer-Versionsconstraint pinnt die Major-Version, die bei einem stable-Vertrag die Einheit für eine Breaking Change ist.

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

Pinnen Sie auf ^3.0, um Minor- und Patch-Releases ohne Breaking Change an einem stable-Vertrag zu erhalten. Pinnen Sie enger, wenn Sie sich auf einen experimental-Vertrag verlassen, weil sich ein experimental-Vertrag in einem Minor-Release ändern kann.

Sonderfälle & Fallstricke

Tag, nicht Sichtbarkeit. Eine public-PHP-Methode ist nicht Teil des Service-Provider-Interface, solange der deklarierende Typ kein @stability-Tag trägt.
Experimental-Drift. Ein experimental-Vertrag kann sich in einem Minor-Release ändern. Pinnen Sie eng oder kapseln Sie ihn hinter einem eigenen Adapter. Das gilt für die Streaming-Verträge, auch wenn sie mit Implementierungen ausgeliefert werden.
Neue Standard-Methoden. Ein stable-Interface kann eine Methode mit einem Standardverhalten erhalten. Implementieren Sie die neue Methode beim Upgrade, um Ihre eigene Implementierung explizit zu halten.
Editions-Parität. NextPDF Pro und NextPDF Enterprise folgen denselben Regeln. Ein Vertrag, den Sie in Core ansprechen, bleibt gegen eine Premium-Implementierung desselben Vertrags gültig.

Deprecation-Lebenszyklus

Ein Vertrag durchläuft einen definierten Lebenszyklus:

Markieren. Der Owner setzt @stability deprecated im PHPDoc der Quelle und hält den Ersatz und die Entfernungs-Version fest.
Hinweis. Die Deprecation wird im Changelog bei dem Release angekündigt, das sie markiert.
Überlappung. Der deprecated Vertrag und sein Ersatz existieren mindestens ein Minor-Release lang nebeneinander.
Entfernen. Der Vertrag wird im genannten Major-Release entfernt. Eine Entfernung passiert nie in einem Minor- oder Patch-Release.

Planen Sie ein Upgrade, sobald ein Vertrag als deprecated markiert ist. Der Ersatz wird immer genannt.

Performance

Diese Seite definiert eine Policy. Sie verursacht keine Laufzeitkosten.

Sicherheitshinweise

Die Signatur-Verträge sind stable und folgen dem Interface-Versprechen. Eine neue Methode an einem Signatur-Vertrag kommt nur mit einem Standardverhalten oder an einem neuen Vertrag, sodass eine hardwaregestützte Implementierung bei einem Minor-Upgrade nicht bricht. Prüfen Sie das Changelog vor einem Major-Upgrade, weil eine Major-Version einen stable-Vertrag ändern kann.

Konformität

Die Versionierungsregel entspricht Semantic Versioning 2.0.0. Die Changelog-Generierung folgt Conventional Commits 1.0.0.

Kommerzieller Kontext

NextPDF Pro und NextPDF Enterprise folgen denselben Stabilitätsregeln des Service-Provider-Interface wie Core. Ein Vertrag, den Sie in Core ansprechen, bleibt gegen die Premium-Implementierung dieses Vertrags gültig, sodass Ihr Erweiterungscode über die Editionen hinweg portabel ist.