Stabiliteitsregels voor de SPI

In het kort

De service provider interface van NextPDF volgt Semantic Versioning. Elk publiek contract heeft een @stability-tag en een belofte voor achterwaartse compatibiliteit. Gebruik deze regels om te bepalen op welke contracten u kunt vertrouwen.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

De service provider interface omvat de publieke contracten in de namespaces NextPDF\Contracts en NextPDF\Event. Een type maakt alleen deel uit van de interface wanneer de PHPDoc in de broncode een @stability-tag bevat. De tag bepaalt de grens. Een type zonder de tag is intern, ook al stelt PHP het beschikbaar als public.

NextPDF volgt Semantic Versioning 2.0.0. Een wijziging die de compatibiliteit van een stable-contract verbreekt, vereist een verhoging van de major-versie. Een nieuw contract of een toevoeging die de compatibiliteit niet verbreekt, verhoogt de minor-versie. Een bugfix verhoogt de patch-versie.

De @stability-tag

Elk contract declareert een van drie stabiliteitswaarden:

Tag	Betekenis	Wijzigingsregel
stable	Klaar voor productie. Veilig om op te vertrouwen.	Geen compatibiliteitsverbrekende wijziging in een minor- of patch-release. Nieuwe methoden worden alleen toegevoegd met standaardgedrag of op een nieuw contract.
experimental	Bruikbaar, maar nog niet bevroren.	De interface kan in een minor-release wijzigen, nadat eerst een afschaffingsmelding is gegeven.
deprecated	Gepland voor verwijdering.	Het contract vermeldt de vervanging en de verwijderingsversie.

NextPDF legt elke belofte per contract vast in de gegenereerde contractenkaart en genereert die bij elke release opnieuw uit de broncode. De beloftetekst geeft de exacte regel voor dat contract. Beschouw de PHPDoc in de broncode van het contract als de enige bron van waarheid.

Klassen van beloften voor achterwaartse compatibiliteit

De contractenkaart deelt elke belofte in een van vier klassen in:

1. Interfacebelofte. „Geen compatibiliteitsverbrekende wijziging in een minor- of patch-release. Nieuwe methoden alleen met een standaardimplementatie.” Geldt voor de meeste stable-interfaces, waaronder FontRegistryInterface, SignerInterface, HsmSignerInterface en HtmlSecurityPolicyInterface.
2. Enumbelofte. „Geen verwijdering van cases. Nieuwe cases kunnen in een minor-versie worden toegevoegd.” Geldt voor stable-enums zoals Alignment, Orientation en OutputDestination.
3. Belofte voor bevroren waardeobjecten. „De constructorsignatuur en de publieke eigenschappen zijn bevroren. Nieuwe methoden kunnen worden toegevoegd.” Geldt voor waardeobjecten zoals TextPreprocessResult, TextSegment en de bijbehorende event-payloads.
4. Experimentele belofte. „De interface kan in een minor-versie wijzigen, met een afschaffingsmelding.” Geldt voor experimental-contracten zoals DeferredSignerInterface, TimestampProviderInterface, CursorInterface en StreamingWriterInterface.

Een final-klasse zoals EventDispatcher of ListenerProvider bevriest zijn publieke methodesignaturen. Gebruik compositie om een final-klasse uit te breiden. Maak er geen subklasse van.

Experimentele streaming-contracten

CursorInterface en StreamingWriterInterface zijn experimental (sinds 3.1.0). NextPDF levert definitieve, geteste engine-implementaties voor beide contracten; de implementatieklassen zijn intern en maken geen deel uit van het publieke oppervlak. U gebruikt streaming-gedrag via het publieke experimental-contract. In de meeste gevallen implementeert u het contract niet zelf.

Omdat het contract experimental is, kan de signatuur ervan in een minor-release wijzigen, nadat eerst een afschaffingsmelding is gegeven (de experimentele belofte). Pin strak of verpak het achter uw eigen adapter voordat u er in productie afhankelijk van wordt. Beschouw het streaming-contract als een stabiliserend uitbreidingspunt, niet als een bevroren punt.

API-oppervlak

Deze pagina heeft geen runtime application programming interface (API). Het relevante oppervlak bestaat uit de @stability-PHPDoc-tag op elk publiek contract en de opnieuw gegenereerde contractenkaart die de belofte per contract samenvoegt.

Codevoorbeeld — Snel aan de slag

Lees de stabiliteit van een contract uit de broncode voordat u er afhankelijk van wordt.

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

Codevoorbeeld — Productie

Een Composer-versiebeperking pint de major-versie vast, waar compatibiliteitsverbrekende wijzigingen voor een stable-contract plaatsvinden.

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

Gebruik ^3.0 om minor- en patch-releases te ontvangen zonder compatibiliteitsverbrekende wijzigingen aan enig stable-contract. Pin strakker wanneer u afhankelijk bent van een experimental-contract, omdat een experimental-contract in een minor-release kan wijzigen.

Randgevallen en valkuilen

• Tag, geen zichtbaarheid. Een PHP-methode die is gemarkeerd als public maakt geen deel uit van de service provider interface, tenzij het declarerende type een @stability-tag heeft.
• Experimentele drift. Een experimental-contract kan in een minor-release wijzigen. Pin strak of verpak het achter uw eigen adapter. Dit geldt voor de streaming-contracten, ook al hebben ze geleverde implementaties.
• Nieuwe standaardmethoden. Een stable-interface kan een methode krijgen die standaardgedrag heeft. Implementeer de nieuwe methode wanneer u upgradet, zodat uw eigen implementatie expliciet blijft.
• Pariteit tussen edities. NextPDF Pro en NextPDF Enterprise volgen dezelfde regels. Een contract waarop u in Core mikt, blijft geldig tegenover een Premium-implementatie van hetzelfde contract.

Levenscyclus van afschaffing

Een contract doorloopt een vastgelegde levenscyclus:

1. Markeren. De eigenaar stelt @stability deprecated in de PHPDoc van de broncode in en legt de vervanging en de verwijderingsversie vast.
2. Melding. De afschaffing wordt aangekondigd in de changelog voor de release waarin deze wordt gemarkeerd.
3. Overlap. Het afgeschafte contract en de vervanging ervan bestaan minstens één minor-release naast elkaar.
4. Verwijderen. Het contract wordt verwijderd in de vermelde major-release. Verwijdering gebeurt nooit in een minor- of patch-release.

Plan een upgrade zodra een contract is gemarkeerd als deprecated. De vervanging wordt altijd vermeld.

Prestaties

Deze pagina definieert beleid. Dat heeft geen runtimekosten.

Beveiligingsopmerkingen

Ondertekeningscontracten zijn stable en volgen de interfacebelofte. Een nieuwe methode op een ondertekeningscontract komt alleen met standaardgedrag of op een nieuw contract, zodat een implementatie met hardwareondersteuning niet breekt bij een minor-upgrade. Bekijk de changelog vóór een major-upgrade, omdat een major-versie een stable-contract kan wijzigen.

Conformiteit

Deze versiebeheerregels voldoen aan Semantic Versioning 2.0.0. Het genereren van de changelog volgt Conventional Commits 1.0.0.

Commerciële context

NextPDF Pro en NextPDF Enterprise volgen dezelfde stabiliteitsregels voor de service provider interface als Core. Een contract waarop u in Core mikt, blijft geldig tegenover de Premium-implementatie van dat contract, zodat uw extensiecode overdraagbaar is tussen edities.

Zie ook

• Overzicht van extensie-ontwikkeling
• Aangepaste lettertypen
• Action triggers en event listeners
• KMS provider contract

Gerelateerde contracten en modules

• Referentie van de Contracts-module — gegenereerde contractenkaart en beloftetekst per contract.
• Referentie van streaming-contracten — experimental streaming-contracten en hun meegeleverde implementaties.
• Referentie van ondertekeningscontracten — stable- en experimental-ondertekeningscontracten onder dezelfde regels.
• Overzicht van extensie-ontwikkeling — wat elke @stability-tag in de praktijk betekent.
• Action triggers en event listeners — de final-dispatcher en experimentele payloads die deze regels beheersen.

De woordenlijst definieert stabiliteitstag en belofte voor achterwaartse compatibiliteit. Raadpleeg de gepubliceerde woordenlijst voor de canonieke definities.