Правила стабильности 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

Каждый контракт объявляет одно из трёх значений стабильности:

Тег	Значение	Правило изменения
`stable`	Готов к промышленной эксплуатации. На него можно безопасно полагаться.	Никаких несовместимых изменений в минорном или патч-выпуске. Новые методы добавляются только с поведением по умолчанию или в новом контракте.
`experimental`	Пригоден к использованию, но ещё не зафиксирован.	Интерфейс может измениться в минорном выпуске, но только после уведомления об устаревании.
`deprecated`	Намечен к удалению.	Контракт указывает замену и версию удаления.

NextPDF записывает обещание для каждого контракта в сгенерированную карту контрактов и заново генерирует её из исходного кода при каждом выпуске. Текст обещания задаёт точное правило для этого контракта. Считайте исходный PHPDoc контракта единственным источником истины.

Классы обещаний обратной совместимости

Карта контрактов записывает каждое обещание в одном из четырёх классов:

Обещание интерфейса. «Никаких несовместимых изменений в минорном или патч-выпуске. Новые методы — только с реализацией по умолчанию.» Применяется к большинству интерфейсов 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 поставляет финальные, протестированные реализации движка для обоих контрактов; классы реализаций являются внутренними и не входят в публичную поверхность. Вы используете потоковое поведение через публичный контракт experimental. В большинстве случаев вам не нужно реализовывать этот контракт самостоятельно.

Поскольку контракт имеет статус experimental, его сигнатура может измениться в минорном выпуске, но только после уведомления об устаревании (экспериментальное обещание). Жёстко зафиксируйте версию или оберните контракт в собственный адаптер, прежде чем полагаться на него в промышленной эксплуатации. Рассматривайте потоковый контракт как стабилизирующуюся точку расширения, а не как зафиксированную.

Поверхность API

На этой странице нет интерфейса прикладного программирования (API) времени выполнения. Соответствующая поверхность — это тег PHPDoc @stability в каждом публичном контракте и заново сгенерированная карта контрактов, которая агрегирует обещание для каждого контракта.

Пример кода — быстрый старт

Считывайте стабильность контракта из исходного кода, прежде чем полагаться на него.

<?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.

Жизненный цикл устаревания

Контракт проходит через определённый жизненный цикл:

Пометка. Владелец устанавливает @stability deprecated в исходном PHPDoc и фиксирует замену и версию удаления.
Уведомление. Об устаревании объявляется в списке изменений выпуска, который помечает контракт.
Сосуществование. Устаревший контракт и его замена сосуществуют не менее одного минорного выпуска.
Удаление. Контракт удаляется в указанном мажорном выпуске. Удаление никогда не происходит в минорном или патч-выпуске.

Планируйте обновление сразу же, как только контракт помечен как deprecated. Замена всегда указана.

Производительность

Эта страница определяет политику. Она не создаёт затрат во время выполнения.

Замечания по безопасности

Контракты подписания имеют статус stable и следуют обещанию интерфейса. Новый метод в контракте подписания появляется только с поведением по умолчанию или в новом контракте, поэтому аппаратно-обеспеченная реализация не ломается при минорном обновлении. Перед мажорным обновлением просмотрите список изменений, поскольку мажорная версия может изменить контракт stable.

Соответствие

Эти правила версионирования соответствуют Semantic Versioning 2.0.0. Генерация списка изменений следует Conventional Commits 1.0.0.

Коммерческий контекст

NextPDF Pro и NextPDF Enterprise следуют тем же правилам стабильности интерфейса поставщика сервисов, что и Core. Контракт, на который вы ориентируетесь в Core, остаётся действительным и для реализации этого контракта в Premium, поэтому код вашего расширения переносится между редакциями.

См. также

Связанные контракты и модули

Справочник модуля контрактов — сгенерированная карта контрактов и текст обещания для каждого контракта.
Справочник потоковых контрактов — потоковые контракты experimental и поставляемые для них реализации.
Справочник контрактов подписания — контракты подписания stable и experimental по тем же правилам.
Обзор разработки расширений — что означает каждый тег @stability на практике.
Триггеры действий и слушатели событий — диспетчер final и экспериментальные полезные нагрузки, которыми управляют эти правила.

В глоссарии определены термины тег стабильности и обещание обратной совместимости. Канонические определения см. в опубликованном глоссарии.