Règles de stabilité de la SPI

En un coup d’œil

L’interface de fournisseur de services de NextPDF suit le versionnage sémantique (Semantic Versioning). Chaque contrat public porte une balise @stability et une promesse de rétrocompatibilité. Cette page précise les règles afin que tu saches sur quels contrats t’appuyer.

Installation

composer require nextpdf/core:^3

Vue d’ensemble conceptuelle

L’interface de fournisseur de services désigne l’ensemble des contrats publics dans les espaces de noms NextPDF\Contracts et NextPDF\Event. Un type n’en fait partie que lorsque son PHPDoc source porte une balise @stability. C’est la balise qui fixe la frontière. Un type sans cette balise est interne, même lorsqu’il est techniquement public en PHP.

NextPDF suit Semantic Versioning 2.0.0. Tout changement cassant sur un contrat stable incrémente la version majeure. Un nouveau contrat ou un ajout non cassant incrémente la version mineure. Une correction de bogue incrémente la version corrective.

La balise @stability

Chaque contrat déclare l’une des trois valeurs de stabilité :

Balise	Signification	Règle de changement
stable	Prêt pour la production. Tu peux t’y fier en toute sécurité.	Aucun changement cassant dans une version mineure ou corrective. De nouvelles méthodes ne sont ajoutées qu’avec un comportement par défaut ou sur un nouveau contrat.
experimental	Utilisable, mais pas encore figé.	L’interface peut changer dans une version mineure, avec un préavis de dépréciation.
deprecated	Prévu pour être supprimé.	Le contrat précise son remplacement et la version de suppression.

La promesse propre à chaque contrat est consignée dans la carte des contrats générée et régénérée depuis la source à chaque publication. Le texte de la promesse formule la règle exacte applicable à ce contrat. Considère le PHPDoc source du contrat comme l’unique source de vérité.

Classes de promesse de rétrocompatibilité

La carte des contrats consigne la promesse. Les promesses se répartissent en quatre classes :

1. Promesse d’interface. « Aucun changement cassant dans une version mineure ou corrective. De nouvelles méthodes uniquement avec une implémentation par défaut. » S’applique à la plupart des interfaces stable, dont FontRegistryInterface, SignerInterface, HsmSignerInterface et HtmlSecurityPolicyInterface.
2. Promesse d’énumération. « Aucune suppression de cas. De nouveaux cas peuvent être ajoutés dans une version mineure. » S’applique aux énumérations stable telles que Alignment, Orientation et OutputDestination.
3. Promesse d’objet-valeur figé. « La signature du constructeur et les propriétés publiques sont figées. De nouvelles méthodes peuvent être ajoutées. » S’applique aux objets-valeurs tels que TextPreprocessResult, TextSegment et les charges utiles d’événement qui y sont liées.
4. Promesse expérimentale. « L’interface peut changer dans une version mineure avec un préavis de dépréciation. » S’applique aux contrats experimental tels que DeferredSignerInterface, TimestampProviderInterface, CursorInterface et StreamingWriterInterface.

Une classe final telle que EventDispatcher ou ListenerProvider fige les signatures de ses méthodes publiques. Étends le comportement d’une classe final par composition. Ne la sous-classe pas.

Contrats de streaming expérimentaux

CursorInterface et StreamingWriterInterface sont experimental (depuis la 3.1.0). NextPDF fournit une implémentation finale et testée, côté moteur, pour chacun des deux contrats ; les classes d’implémentation sont internes et ne font pas partie de la surface publique. Tu utilises le comportement de streaming à travers le contrat public experimental. Dans le cas courant, tu n’implémentes pas le contrat toi-même.

Comme le contrat est experimental, sa signature peut changer dans une version mineure, avec un préavis de dépréciation (la promesse expérimentale). Épingle-le strictement ou enveloppe-le derrière ton propre adaptateur avant de t’y appuyer en production. Considère le contrat de streaming comme un point d’extension en cours de stabilisation, pas comme une surface figée.

Surface de l’API

Cette page ne définit aucune API d’exécution. La surface pertinente est la balise PHPDoc @stability sur chaque contrat public et la carte des contrats régénérée, qui agrège la promesse propre à chaque contrat.

Exemple de code — Démarrage rapide

Vérifie la stabilité d’un contrat dans sa source avant de t’y appuyer.

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

Exemple de code — Production

Une contrainte de version Composer épingle la version majeure, qui est l’unité de changement cassant pour un contrat stable.

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

Utilise ^3.0 pour recevoir les versions mineures et correctives sans changement cassant sur aucun contrat stable. Épingle plus strictement lorsque tu t’appuies sur un contrat experimental, car un contrat experimental peut changer dans une version mineure.

Cas limites et pièges

• La balise, pas la visibilité. Une méthode PHP public ne fait pas partie de l’interface de fournisseur de services tant que son type déclarant ne porte pas de balise @stability.
• Évolution expérimentale. Un contrat experimental peut changer dans une version mineure. Épingle-le strictement ou enveloppe-le derrière ton propre adaptateur. Cela s’applique aux contrats de streaming, même s’ils sont livrés avec des implémentations.
• Nouvelles méthodes par défaut. Une interface stable peut recevoir une méthode dotée d’un comportement par défaut. Implémente la nouvelle méthode au moment de la mise à niveau pour que ta propre implémentation reste explicite.
• Parité entre éditions. NextPDF Pro et NextPDF Enterprise suivent les mêmes règles. Un contrat que tu cibles dans Core reste valide face à une implémentation Premium du même contrat.

Cycle de vie de la dépréciation

Un contrat traverse un cycle de vie défini :

1. Marquage. Le propriétaire définit @stability deprecated dans le PHPDoc source et renseigne le remplacement et la version de suppression.
2. Avis. La dépréciation est annoncée dans le journal des modifications de la version où elle est marquée.
3. Chevauchement. Le contrat déprécié et son remplacement coexistent pendant au moins une version mineure.
4. Suppression. Le contrat est supprimé dans la version majeure indiquée. La suppression n’a jamais lieu dans une version mineure ou corrective.

Planifie une mise à niveau dès qu’un contrat est marqué deprecated. Son remplacement est toujours indiqué.

Performance

Cette page définit une politique. Elle n’a aucun coût d’exécution.

Notes de sécurité

Les contrats de signature sont stable et suivent la promesse d’interface. Une nouvelle méthode sur un contrat de signature n’est ajoutée qu’avec un comportement par défaut ou sur un nouveau contrat, si bien qu’une implémentation adossée à du matériel continue de fonctionner lors d’une mise à niveau mineure. Relis le journal des modifications avant une mise à niveau majeure, car une version majeure peut changer un contrat stable.

Conformité

La règle de versionnage est conforme à Semantic Versioning 2.0.0. La génération du journal des modifications suit Conventional Commits 1.0.0.

Contexte commercial

NextPDF Pro et NextPDF Enterprise suivent les mêmes règles de stabilité de l’interface de fournisseur de services que Core. Un contrat que tu cibles dans Core reste valide avec l’implémentation Premium de ce contrat, si bien que ton code d’extension est portable entre les éditions.

Voir aussi

• Aperçu de la création d’extensions
• Polices personnalisées
• Déclencheurs d’action et écouteurs d’événements
• Contrat de fournisseur KMS

Contrats et modules connexes

• Référence du module des contrats — la carte des contrats générée et le texte de la promesse propre à chaque contrat.
• Référence des contrats de streaming — les contrats de streaming experimental et leurs implémentations livrées.
• Référence des contrats de signature — les contrats de signature stable et experimental sous les mêmes règles.
• Aperçu de la création d’extensions — ce que signifie chaque balise @stability en pratique.
• Déclencheurs d’action et écouteurs d’événements — le distributeur final et les charges utiles expérimentales dont les règles sont définies ici.

Le glossaire définit balise de stabilité et promesse de rétrocompatibilité ; consulte le glossaire publié pour chaque définition canonique.