Release — глубокий справочник

Краткий обзор

Пространство имён NextPDF\Enterprise\Release моделирует выпуск продукта как неизменяемые типизированные объекты-значения. Его публичная поверхность — семь final-классов и пять перечислений на основе строк. ReleaseManifest агрегирует записи ArtifactManifest по каждому артефакту плюс пути к доказательствам цепочки поставок. BuildProfile — единственный источник истины для одного варианта артефакта. ArtifactNamer и PackageMapping выводят детерминированные имена файлов и идентичность пакета Composer из профиля. PublishingPlan::fromProfiles разрешает каждый профиль в типизированные записи PublishingTarget с правильным каналом и границей доступа. ReleaseStatus типизирует жизненный цикл выпуска. Модуль не выполняет ввода-вывода, сетевых вызовов и криптографии; это чистое моделирование метаданных.

Доступность и лицензирование

Эта возможность поставляется в составе NextPDF Enterprise (nextpdf/enterprise) и активируется лицензионным конвертом уровня Enterprise. Развёртывание без такого права не загружает классы возможности. Сравните редакции и получите лицензию.

Эта поверхность лицензируется границей пакета nextpdf/enterprise и не имеет отдельного кода возможности для каждой функции. Core и Pro не поставляют слой моделирования выпусков.

Поверхность публичного API

composer require nextpdf/enterprise:^3

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается с	Примечания
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	Создаёт неизменяемый документ выпуска верхнего уровня	экземпляр	—	final readonly; SCHEMA_VERSION равно '1.0'; minor для добавляемых полей, major для несовместимых; начиная с 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	Предварительно задаёт имена файлов SBOM, подписи и контрольной суммы по умолчанию через ArtifactNamer	self	—	Канонная точка входа для сборщиков выпуска; используйте конструктор, чтобы переопределить отдельные пути
ReleaseManifest::toArray / ::toJson	нет	Сериализует манифест со всеми записями артефактов	array / строка JSON	toJson: JsonException при ошибке кодирования	С отступами, без экранирования слэшей; built_at в формате ATOM
ReleaseManifest::validate	нет	Проверяет, что список артефактов не пуст и каждый артефакт соответствует версии и коммиту выпуска	list<string> ошибок; пустой означает валидность	Никогда не бросает	Вызывающий код должен считать непустой список дефектом
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	Фиксирует один собранный артефакт: что собрано, как и как это проверить	экземпляр	—	final readonly; ioncubeExpire равно null для неистекающих артефактов
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	Выводит имя файла и все измерения профиля	self	—	builtAt по умолчанию — текущее время
ArtifactManifest::toArray	нет	Сериализует для кодирования в JSON	array<string, string|null>	—	Поля-перечисления сериализуются в свои строковые значения
BuildProfile::__construct / ::fromArray	поля профиля / array $data	Определяет один вариант артефакта; единственный источник истины для именования, манифеста и плана	экземпляр / self	fromArray: InvalidArgumentException при отсутствующем или пустом обязательном поле	Обязательные ключи: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	нет	Предикатные помощники над измерениями профиля	bool	—	Кодирование требует одновременно DeliveryMode::Encoded и EncodingTechnology::IonCube
ArtifactNamer::format	BuildProfile $profile, string $version	Выдаёт nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip	non-empty-string	—	Детерминированно; точки удаляются из целевой версии PHP (8.4 становится php84)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile: нет)	Выдаёт SHA256SUMS-{v}.txt, SHA256SUMS-{v}.txt.asc, sbom-{v}.cdx.json, release-manifest.json	non-empty-string	—	Имя файла SBOM совпадает с документом CycloneDX, который пишет генератор SBOM ядра Core
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	Сопоставляет с nextpdf/pro или nextpdf/enterprise; ознакомительный канал добавляет -evaluation	non-empty-string	InvalidArgumentException при неизвестной редакции	Отдельное пространство имён для ознакомления предотвращает смешение с платными артефактами
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	Разрешает URL загрузки артефакта в каноническом репозитории артефактов	non-empty-string	—	Кодированный и открытый вариант используют одно имя пакета; их dist-URL различаются
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / нет / нет / нет	Граница следует за каналом лицензии; фиксированные каналы источника и потребления; все клиентские имена пакетов	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core не является премиум-пакетом и исключён из списка имён
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	Разрешает две цели на профиль: одну — источник артефакта, одну — слой потребления	self	—	Окружение по умолчанию — Staging; production всегда явный выбор
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / нет	Помощники фильтрации и перечисления над разрешёнными целями	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames отсортирован и без дубликатов
PublishingPlan::validate	нет	Проверяет, что цели не пусты, версии совпадают с планом и ни один ознакомительный пакет не находится в платной границе	list<string> ошибок; пустой означает валидность	Никогда не бросает	Запускайте перед любым шагом загрузки
PublishingPlan::toArray	нет	Сериализует для вывода dry-run и журналирования	array<string, mixed>	—	Включает target_count и список пакетов
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	Разрешает имя пакета, границу доступа и имя файла артефакта для одного канала	self	—	final readonly; toArray сериализует для журналирования
AccessBoundary	перечисление: Paid, Evaluation, Internal	isCustomerFacing равно true только для Paid и Evaluation	на основе 'paid', 'evaluation', 'internal'	—	requiresAuthentication возвращает true для каждой границы
DistributionChannel	перечисление: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin и isConsumptionLayer разделяют две роли	на основе 'github_releases', 'private_packagist', 'direct_download'	—	DirectDownload зарезервирован для будущего канала с подписанными URL
EncodingTechnology	перечисление: IonCube, None	Именует инструмент кодирования, отдельно от формы доставки	на основе 'ioncube', 'none'	—	Артефакт в открытом тексте всегда сообщает None
PublishingEnvironment	перечисление: Staging, Production	isCustomerFacing равно true только для Production	на основе 'staging', 'production'	—	Staging — внутренняя цель проверки
ReleaseStatus	перечисление: Built, Audited, Staged, Published, Revoked, Superseded	canPromote, nextStatus, isCustomerVisible, isTerminal типизируют жизненный цикл	nextStatus возвращает ?self	—	Цепочка продвижения Built → Audited → Staged → Published; Revoked и Superseded терминальны

Сигнатуры точек входа, дословно из исходного кода:

public static function createWithDefaults(string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []): self

public static function fromProfile(BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null): self

public static function fromArray(array $data): self

public static function format(BuildProfile $profile, string $version): string

public static function fromProfiles(array $profiles, string $version, PublishingEnvironment $environment = PublishingEnvironment::Staging): self

public static function fromProfile(BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel): self

Контракт поведения

• Каждый класс final; каждый класс-значение readonly. Конструирование фиксирует всё состояние. Модуль не выполняет операций с файловой системой, сетью или криптографией.
• ReleaseManifest — неизменяемый документ верхнего уровня для версии: семантическая версия, исходный коммит, временная метка сборки, список артефактов и необязательные пути к доказательствам цепочки поставок (SBOM, подпись GPG, контрольные суммы). Версия схемы — minor для добавлений и major для несовместимых изменений.
• BuildProfile — единственный источник истины о том, что содержит артефакт и как он упакован. Именование, манифест и план выводятся из профиля; вторичного источника конфигурации нет.
• EncodingTechnology именует инструмент кодирования; DeliveryMode (из модуля Licensing) именует форму доставки. Эти два понятия намеренно разделены, и артефакт в открытом тексте всегда сообщает EncodingTechnology::None.
• DistributionChannel разделяет источник артефакта (двоичное хранилище; место назначения загрузки) и слой потребления пакета (реестр, который читает composer require). Источник хранит двоичный файл; слой потребления отдаёт метаданные, указывающие на него.
• AccessBoundary перечисляет Paid, Evaluation и Internal. Каждая граница требует аутентификации. Артефакты Internal обслуживают CI, QA и staging и никогда не предназначены для клиента.
• PublishingPlan::fromProfiles разрешает каждый профиль ровно в две цели: цель источника артефакта и цель слоя потребления, при этом граница доступа выводится из канала лицензии профиля, чтобы платные и ознакомительные артефакты маршрутизировались корректно.
• План описывает предполагаемые цели, а не транспорт. Фактическую загрузку выполняет окружающий инструментарий выпуска, а манифест фиксирует — но сам не создаёт — доказательства цепочки поставок.
• ReleaseStatus типизирует жизненный цикл: Built → Audited → Staged → Published, где Revoked и Superseded — терминальные выходы из Published. Только Published виден клиенту; canPromote равно false, начиная с Published.
• ReleaseManifest::validate и PublishingPlan::validate сообщают об ошибках согласованности списками строк и никогда не бросают исключений. Пустой список — единственный валидный результат.

Граничные случаи и режимы отказа

• BuildProfile::fromArray с отсутствующим, нестроковым или пустым обязательным полем: InvalidArgumentException с указанием поля.
• BuildProfile::fromArray с пустым или нестроковым ioncube_expire: нормализуется в null (без истечения). Нестроковые или пустые записи в encode_paths и exclude_paths тихо отбрасываются.
• PackageMapping::resolvePackageName с редакцией вне известной карты: InvalidArgumentException.
• ReleaseManifest::toJson на некодируемых данных: JsonException. Сериализация использует JSON_THROW_ON_ERROR; тихого запасного варианта нет.
• ReleaseManifest::validate сообщает об ошибках при пустом списке артефактов и о любом артефакте, чья версия или исходный коммит отличаются от выпуска.
• PublishingPlan::validate сообщает о пустом списке целей, любой версии цели, расходящейся с планом, и любом ознакомительном пакете, попавшем в платную границу.
• ReleaseStatus::nextStatus возвращает null из Published, Revoked и Superseded. Вызывающий код должен обрабатывать null; зацикливания нет.
• Каналы источника и слоя потребления различны; не направляйте composer require на источник артефакта.
• Артефакты с границей Internal никогда не предназначены для клиента; их маршрутизация в клиентский канал — явная ошибка моделирования.
• Этот модуль не выполняет криптографических операций. Подписание GPG и генерация контрольных сумм являются внешними и здесь только упоминаются.

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

Соответствие стандартам для этого модуля не заявляется; это слой моделирования выпусков, и NextPDF не имеет сертификации. Имя файла SBOM по умолчанию (sbom-{version}.cdx.json) совпадает с документом CycloneDX, который пишет генератор SBOM ядра Core; манифест ссылается на это доказательство и не проверяет его. Подписи GPG и контрольные суммы создаются и проверяются окружающим конвейером выпуска. Запись пути к доказательству — это возможность, а не аттестация: манифест сам по себе не является доказательством, не подтверждает происхождение, не сертифицирует выпуск и не является юридической консультацией.

Заметки по разработке

• Предпочитайте ReleaseManifest::createWithDefaults, чтобы имена файлов доказательств всегда согласовывались с ArtifactNamer. Оставляйте прямой конструктор для намеренного переопределения отдельных путей.
• Запускайте оба гейта validate() в CI перед любым шагом публикации и завершайте конвейер с ошибкой при непустом списке ошибок.
• PublishingPlan::fromProfiles по умолчанию использует PublishingEnvironment::Staging. Передавайте Production явно; ничто в этом модуле не продвигает окружение неявно.
• Сериализованные манифесты несут строковые значения перечислений (paid, encoded, ioncube и так далее) и временные метки ATOM; относитесь к этим строкам как к сетевому контракту.
• Ознакомительные артефакты живут в отдельном пространстве имён пакетов (суффикс -evaluation). Держите платные и ознакомительные реестры раздельно в конфигурации Composer.
• Маршрутизация по каналам, учётные данные и хранение — ответственность оператора. План сообщает инструментарию, куда относится артефакт, а не как к нему аутентифицироваться.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую поверхность публичного API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов вне области рассмотрения.

См. также

• Release (страница возможности)
• Licensing — углублённый справочник — перечисления LicenseEdition, LicenseChannel и DeliveryMode, которые используют профили.
• Обзор Enterprise
• Активация лицензии