SPI の安定性ルール

概要

NextPDF のサービスプロバイダーインターフェイスは、セマンティックバージョニング（Semantic Versioning）に従います。各パブリックコントラクトには @stability タグと後方互換性の約束があります。このページでは、何に依存してよいかを判断できるよう、そのルールを説明します。

インストール

composer require nextpdf/core:^3

概念の概要

サービスプロバイダーインターフェイスは、NextPDF\Contracts および NextPDF\Event 名前空間に含まれるパブリックコントラクトの集合です。型は、そのソース PHPDoc に @stability タグが付いている場合にのみ、インターフェイスの一部となります。このタグが境界を定義します。タグのない型は、PHP の仕様上 public であっても内部扱いです。

NextPDF はセマンティックバージョニング（Semantic Versioning） 2.0.0 に従います。stable コントラクトに対する破壊的変更では、メジャーバージョンを上げます。新しいコントラクトや破壊的でない追加では、マイナーバージョンを上げます。バグ修正では、パッチバージョンを上げます。

@stability タグ

各コントラクトは、3 つの安定性値のいずれかを宣言します。

タグ	意味	変更ルール
`stable`	本番環境で使用可能。安全に依存可能。	マイナーリリースまたはパッチリリースでの破壊的変更なし。新しいメソッドは、デフォルトの動作を伴う場合、または新しいコントラクト上でのみ追加。
`experimental`	使用可能だが、まだ未固定。	インターフェイスはマイナーリリースで変更される可能性あり。その場合は事前に非推奨を通知。
`deprecated`	削除予定。	コントラクトには、代替手段と削除バージョンを記載。

コントラクトごとの約束は、生成されたコントラクトマップに記録され、リリースごとにソースから再生成されます。約束のテキストには、そのコントラクトに適用される正確なルールが記載されています。唯一の信頼できる情報源として、コントラクトのソース PHPDoc を参照してください。

後方互換性の約束のクラス

コントラクトマップには約束が記録されます。約束は 4 つのクラスに分類されます。

インターフェイスの約束。 「マイナーリリースまたはパッチリリースでの破壊的変更なし。新しいメソッドはデフォルト実装を伴う場合のみ。」ほとんどの stable インターフェイス（FontRegistryInterface、SignerInterface、HsmSignerInterface、HtmlSecurityPolicyInterface を含む）に適用されます。
列挙型の約束。 「ケースの削除なし。新しいケースはマイナーバージョンで追加される場合がある。」 stable 列挙型（Alignment、Orientation、OutputDestination など）に適用されます。
固定された値オブジェクトの約束。 「コンストラクターのシグネチャとパブリックプロパティは固定。新しいメソッドは追加される場合がある。」 TextPreprocessResult、TextSegment などの値オブジェクト、およびそれにバインドされたイベントペイロードに適用されます。
実験的な約束。 「インターフェイスは非推奨の通知を伴ってマイナーバージョンで変更される場合がある。」 experimental コントラクト（DeferredSignerInterface、TimestampProviderInterface、CursorInterface、StreamingWriterInterface など）に適用されます。

final 修飾子を持つクラス（EventDispatcher や ListenerProvider など）は、そのパブリックメソッドのシグネチャを固定します。final クラスを拡張する場合は、コンポジションを使用してください。サブクラス化しないでください。

実験的なストリーミングコントラクト

CursorInterface と StreamingWriterInterface は experimental です（3.1.0 以降）。NextPDF は、両方のコントラクトについて、final でテスト済みのエンジン実装を提供します。実装クラスは内部用であり、パブリックなサーフェスの一部ではありません。ストリーミングの動作は、パブリックな experimental コントラクトを通じて利用します。一般的なケースでは、コントラクトを自分で実装する必要はありません。

このコントラクトは experimental であるため、そのシグネチャはマイナーリリースで変更される可能性があり、その際は事前に非推奨の通知が行われます（実験的な約束）。本番環境で依存する前に、厳密にバージョンを固定するか、独自のアダプターでラップしてください。ストリーミングコントラクトは、固定済みの拡張ポイントではなく、安定化が進行中の拡張ポイントとして扱ってください。

API サーフェス

このページには実行時 API はありません。関連するサーフェスは、すべてのパブリックコントラクトに付く @stability PHPDoc タグと、コントラクトごとの約束を aggregate（集約）する、再生成されたコントラクトマップです。

コードサンプル — クイックスタート

コントラクトに依存する前に、そのソースで安定性を確認してください。

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

コードサンプル — 本番環境

Composer のバージョン制約はメジャーバージョンを固定します。これは stable コントラクトにおける破壊的変更の単位です。

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

バージョンを ^3.0 に固定すると、どの stable コントラクトにも破壊的変更が入らない範囲で、マイナーリリースおよびパッチリリースを受け取れます。experimental コントラクトに依存する場合は、より厳密に固定してください。experimental コントラクトはマイナーリリースで変更される可能性があるためです。

エッジケースと注意点

可視性ではなくタグ。 PHP の public メソッドは、その宣言元の型に @stability タグが付いていない限り、サービスプロバイダーインターフェイスの一部にはなりません。
実験的コントラクトのドリフト。 experimental コントラクトはマイナーリリースで変更されることがあります。厳密にバージョンを固定するか、独自のアダプターでラップしてください。これは、ストリーミングコントラクトに実装が提供されている場合でも当てはまります。
新しいデフォルトメソッド。 stable インターフェイスには、デフォルトの動作を持つメソッドが追加される場合があります。独自実装の挙動を明確に保つため、アップグレード時には新しいメソッドを実装してください。
エディション間の同等性。 NextPDF Pro と NextPDF Enterprise も同じルールに従います。Core で対象とするコントラクトは、同じコントラクトの Premium 実装に対しても有効なままです。

非推奨ライフサイクル

コントラクトは、定義されたライフサイクルに沿って移行します。

マーク。 オーナーがソース PHPDoc に @stability deprecated を設定し、代替手段と削除バージョンを記録します。
通知。 非推奨は、それをマークするリリースの変更履歴で告知されます。
重複期間。 非推奨のコントラクトとその代替手段は、少なくとも 1 つのマイナーリリースの間、共存します。
削除。 コントラクトは、記載されたメジャーリリースで削除されます。削除がマイナーリリースやパッチリリースで行われることはありません。

コントラクトが deprecated としてマークされたら、すぐにアップグレードを計画してください。代替手段は必ず記載されます。

パフォーマンス

このページはポリシーを定義します。実行時コストはありません。

セキュリティに関する注意事項

署名コントラクトは stable であり、インターフェイスの約束に従います。署名コントラクトの新しいメソッドは、デフォルトの動作を伴う場合、または新しいコントラクト上でのみ追加されるため、ハードウェアベースの実装がマイナーアップグレードで壊れることはありません。メジャーバージョンでは stable コントラクトが変更される可能性があるため、メジャーアップグレードの前に変更履歴を確認してください。

準拠

バージョニングルールはセマンティックバージョニング（Semantic Versioning） 2.0.0 に準拠します。変更履歴の生成は Conventional Commits 1.0.0 に従います。

商用に関する補足

NextPDF Pro と NextPDF Enterprise は、Core と同じサービスプロバイダーインターフェイスの安定性ルールに従います。Core で対象とするコントラクトは、そのコントラクトの Premium 実装に対しても有効なままであるため、拡張機能のコードはエディション間で移植できます。