Enterprise phiên bản

Release — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Namespace NextPDF\Enterprise\Release mô hình hóa một bản phát hành sản phẩm thành các value object bất biến, có kiểu. Bề mặt công khai của nó gồm bảy lớp final và năm enum được hậu thuẫn bằng chuỗi. ReleaseManifest gộp các mục ArtifactManifest theo từng artifact cùng các đường dẫn bằng chứng chuỗi cung ứng. BuildProfile là nguồn chân lý duy nhất cho một biến thể artifact. ArtifactNamer và PackageMapping suy dẫn tên tệp tất định và định danh gói Composer từ một hồ sơ. PublishingPlan::fromProfiles phân giải mọi hồ sơ thành các mục PublishingTarget có kiểu với đúng kênh và ranh giới truy cập. ReleaseStatus gán kiểu cho vòng đời bản phát hành. Module không thực hiện I/O, không gọi mạng, và không mật mã; nó thuần túy là mô hình hóa siêu dữ liệu.

Tính khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một envelope giấy phép hạng Enterprise. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Bề mặt này được cấp phép theo ranh giới gói nextpdf/enterprise và không có mã năng lực riêng theo từng tính năng. Core và Pro không đi kèm một lớp mô hình hóa bản phát hành.

Bề mặt API công khai

composer require nextpdf/enterprise:^3

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`ReleaseManifest::__construct`	`version`, `sourceCommit`, `builtAt`, `artifacts = []`, `sbomPath = null`, `gpgSignature = null`, `checksumPath = null`	Dựng tài liệu bản phát hành cấp cao nhất, bất biến	thể hiện	—	`final readonly`; `SCHEMA_VERSION` là `'1.0'`; minor cho các trường thêm mới, major cho phá vỡ; từ 3.0.0
`ReleaseManifest::createWithDefaults`	`string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []`	Đấu sẵn các tên tệp SBOM, chữ ký, và checksum mặc định thông qua `ArtifactNamer`	`self`	—	Điểm vào chuẩn tắc cho các trình dựng bản phát hành; dùng constructor để ghi đè từng đường dẫn riêng
`ReleaseManifest::toArray` / `::toJson`	không	Tuần tự hóa manifest cùng mọi mục artifact	chuỗi `array` / JSON	`toJson`: `JsonException` khi mã hóa thất bại	In đẹp, không escape dấu gạch chéo; `built_at` ở định dạng ATOM
`ReleaseManifest::validate`	không	Kiểm tra danh sách artifact không rỗng và mọi artifact khớp với phiên bản và commit của bản phát hành	`list<string>` các lỗi; rỗng nghĩa là hợp lệ	Không bao giờ ném	Bên gọi phải xem một danh sách không rỗng là một khiếm khuyết
`ArtifactManifest::__construct`	`filename`, `version`, `sourceCommit`, `edition`, `deliveryMode`, `encodingTechnology`, `channel`, `phpTarget`, `sha256`, `ioncubeExpire`, `builtAt`	Ghi lại một artifact đã build: build cái gì, bằng cách nào, và xác minh nó ra sao	thể hiện	—	`final readonly`; `ioncubeExpire` là `null` cho các artifact không hết hạn
`ArtifactManifest::fromProfile`	`BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null`	Suy dẫn tên tệp và mọi chiều của hồ sơ	`self`	—	`builtAt` mặc định là thời điểm hiện tại
`ArtifactManifest::toArray`	không	Tuần tự hóa để mã hóa JSON	`array<string, string\|null>`	—	Các trường enum tuần tự hóa thành các giá trị chuỗi hậu thuẫn của chúng
`BuildProfile::__construct` / `::fromArray`	các trường hồ sơ / `array $data`	Định nghĩa một biến thể artifact; nguồn chân lý duy nhất cho việc đặt tên, manifest, và kế hoạch	thể hiện / `self`	`fromArray`: `InvalidArgumentException` khi một trường bắt buộc thiếu hoặc rỗng	Các khóa bắt buộc: `name`, `edition`, `delivery`, `encoding_technology`, `channel`, `php_target`
`BuildProfile::requiresEncoding` / `::isEvaluation`	không	Các trợ thủ vị từ trên các chiều của hồ sơ	`bool`	—	Mã hóa yêu cầu `DeliveryMode::Encoded` và `EncodingTechnology::IonCube` cùng lúc
`ArtifactNamer::format`	`BuildProfile $profile, string $version`	Phát ra `nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip`	`non-empty-string`	—	Tất định; các dấu chấm bị bỏ khỏi PHP target (`8.4` trở thành `php84`)
`ArtifactNamer::checksumFile` / `::signatureFile` / `::sbomFile` / `::manifestFile`	`string $version` (`manifestFile`: không)	Phát ra `SHA256SUMS-{v}.txt`, `SHA256SUMS-{v}.txt.asc`, `sbom-{v}.cdx.json`, `release-manifest.json`	`non-empty-string`	—	Tên tệp SBOM khớp với tài liệu CycloneDX mà trình sinh SBOM của core ghi ra
`PackageMapping::packageName` / `::resolvePackageName`	`BuildProfile` / `LicenseEdition` + `LicenseChannel`	Ánh xạ tới `nextpdf/pro` hoặc `nextpdf/enterprise`; kênh evaluation thêm hậu tố `-evaluation`	`non-empty-string`	`InvalidArgumentException` khi phiên bản không xác định	Namespace evaluation riêng ngăn việc trộn lẫn với các artifact trả phí
`PackageMapping::distUrlPattern`	`BuildProfile $profile, string $version`	Phân giải URL tải artifact trên kho artifact chuẩn tắc	`non-empty-string`	—	Bản mã hóa và bản cleartext dùng chung một tên gói; URL dist của chúng khác nhau
`PackageMapping::accessBoundary` / `::artifactOrigin` / `::consumptionChannel` / `::allPackageNames`	`BuildProfile` / không / không / không	Ranh giới theo kênh giấy phép; origin cố định và kênh tiêu thụ; mọi tên gói hướng tới khách hàng	`AccessBoundary` / `DistributionChannel` / `DistributionChannel` / `list<non-empty-string>`	—	Core không phải là gói premium và bị loại khỏi danh sách tên
`PublishingPlan::fromProfiles`	`array $profiles, string $version, PublishingEnvironment $environment = Staging`	Phân giải hai đích cho mỗi hồ sơ: một origin artifact, một lớp tiêu thụ	`self`	—	Environment mặc định là `Staging`; production luôn là một lựa chọn tường minh
`PublishingPlan::targetsByBoundary` / `::targetsByChannel` / `::packageNames`	`AccessBoundary` / `DistributionChannel` / không	Các trợ thủ lọc và liệt kê trên các đích đã phân giải	`list<PublishingTarget>` / `list<PublishingTarget>` / `list<non-empty-string>`	—	`packageNames` được sắp xếp và khử trùng lặp
`PublishingPlan::validate`	không	Kiểm tra các đích không rỗng, các phiên bản khớp với kế hoạch, và không có gói evaluation nào nằm trong một ranh giới trả phí	`list<string>` các lỗi; rỗng nghĩa là hợp lệ	Không bao giờ ném	Chạy trước mọi bước upload
`PublishingPlan::toArray`	không	Tuần tự hóa để xuất dry-run và ghi log	`array<string, mixed>`	—	Bao gồm `target_count` và danh sách gói
`PublishingTarget::fromProfile`	`BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel`	Phân giải tên gói, ranh giới truy cập, và tên tệp artifact cho một kênh	`self`	—	`final readonly`; `toArray` tuần tự hóa để ghi log
`AccessBoundary`	enum: `Paid`, `Evaluation`, `Internal`	`isCustomerFacing` là `true` chỉ cho `Paid` và `Evaluation`	được hậu thuẫn bằng `'paid'`, `'evaluation'`, `'internal'`	—	`requiresAuthentication` trả về `true` cho mọi ranh giới
`DistributionChannel`	enum: `GitHubReleases`, `PrivatePackagist`, `DirectDownload`	`isArtifactOrigin` và `isConsumptionLayer` tách hai vai trò	được hậu thuẫn bằng `'github_releases'`, `'private_packagist'`, `'direct_download'`	—	`DirectDownload` được dành riêng cho một kênh signed-URL trong tương lai
`EncodingTechnology`	enum: `IonCube`, `None`	Đặt tên cho công cụ mã hóa, khác biệt với hình thức phân phối	được hậu thuẫn bằng `'ioncube'`, `'none'`	—	Một artifact cleartext luôn báo cáo `None`
`PublishingEnvironment`	enum: `Staging`, `Production`	`isCustomerFacing` là `true` chỉ cho `Production`	được hậu thuẫn bằng `'staging'`, `'production'`	—	Staging là một đích xác minh nội bộ
`ReleaseStatus`	enum: `Built`, `Audited`, `Staged`, `Published`, `Revoked`, `Superseded`	`canPromote`, `nextStatus`, `isCustomerVisible`, `isTerminal` gán kiểu cho vòng đời	`nextStatus` trả về `?self`	—	Chuỗi thăng tiến Built → Audited → Staged → Published; `Revoked` và `Superseded` là điểm cuối

Chữ ký của các điểm vào, nguyên văn từ mã nguồn:

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

Hợp đồng hành vi

Mọi lớp đều final; mọi value class đều readonly. Việc dựng cố định toàn bộ trạng thái. Module không thực hiện thao tác hệ thống tệp, mạng, hay mật mã.
ReleaseManifest là tài liệu cấp cao nhất, bất biến cho một phiên bản: phiên bản ngữ nghĩa, source commit, dấu thời gian build, danh sách artifact, và các đường dẫn bằng chứng chuỗi cung ứng tùy chọn (SBOM, chữ ký GPG, checksum). Phiên bản schema của nó là minor-cho-thêm-mới và major-cho-phá-vỡ.
BuildProfile là nguồn chân lý duy nhất cho việc một artifact chứa gì và được đóng gói ra sao. Việc đặt tên, manifest, và kế hoạch đều suy dẫn từ hồ sơ; không có nguồn cấu hình thứ cấp.
EncodingTechnology đặt tên cho công cụ mã hóa; DeliveryMode (từ module Licensing) đặt tên cho hình thức được phân phối. Hai bên được chủ ý tách biệt, và một artifact cleartext luôn báo cáo EncodingTechnology::None.
DistributionChannel tách một origin artifact (lưu trữ nhị phân; nơi đích để upload) khỏi một lớp tiêu thụ gói (registry mà một composer require đọc). Origin lưu trữ tệp nhị phân; lớp tiêu thụ phục vụ siêu dữ liệu trỏ tới nó.
AccessBoundary liệt kê Paid, Evaluation, và Internal. Mọi ranh giới đều yêu cầu xác thực. Các artifact Internal phục vụ CI, QA, và staging và không bao giờ hướng tới khách hàng.
PublishingPlan::fromProfiles phân giải mỗi hồ sơ thành đúng hai đích: một đích origin artifact và một đích lớp tiêu thụ, với ranh giới truy cập được suy dẫn từ kênh giấy phép của hồ sơ để các artifact paid và evaluation được định tuyến chính xác.
Kế hoạch mô tả các đích dự kiến, không phải kênh truyền tải. Việc upload thực tế do bộ công cụ phát hành bao quanh thực hiện, và manifest ghi lại — nhưng tự nó không tạo ra — bằng chứng chuỗi cung ứng.
ReleaseStatus gán kiểu cho vòng đời: Built → Audited → Staged → Published, với Revoked và Superseded là các lối ra điểm cuối từ Published. Chỉ Published là hiển thị với khách hàng; canPromote là false kể từ Published trở đi.
ReleaseManifest::validate và PublishingPlan::validate báo cáo các lỗi nhất quán dưới dạng danh sách chuỗi và không bao giờ ném. Một danh sách rỗng là kết quả hợp lệ duy nhất.

Trường hợp biên & chế độ thất bại

BuildProfile::fromArray với một trường bắt buộc thiếu, không phải chuỗi, hoặc rỗng: InvalidArgumentException nêu tên trường.
BuildProfile::fromArray với một ioncube_expire rỗng hoặc không phải chuỗi: chuẩn hóa thành null (không hết hạn). Các mục không phải chuỗi hoặc rỗng trong encode_paths và exclude_paths bị âm thầm loại bỏ.
PackageMapping::resolvePackageName với một phiên bản ngoài bản đồ đã biết: InvalidArgumentException.
ReleaseManifest::toJson trên dữ liệu không mã hóa được: JsonException. Việc tuần tự hóa dùng JSON_THROW_ON_ERROR; không có fallback âm thầm.
ReleaseManifest::validate báo cáo một danh sách artifact rỗng, và bất kỳ artifact nào có phiên bản hoặc source commit khác với bản phát hành, dưới dạng lỗi.
PublishingPlan::validate báo cáo một danh sách đích rỗng, bất kỳ phiên bản đích nào lệch khỏi kế hoạch, và bất kỳ gói evaluation nào được phân giải vào một ranh giới trả phí.
ReleaseStatus::nextStatus trả về null từ Published, Revoked, và Superseded. Bên gọi phải xử lý null; không có vòng lặp lại.
Các kênh origin và lớp tiêu thụ là khác biệt; đừng trỏ một composer require tới origin artifact.
Các artifact thuộc ranh giới Internal không bao giờ hướng tới khách hàng; định tuyến chúng tới một kênh khách hàng là một lỗi mô hình hóa tường minh.
Module này không thực hiện thao tác mật mã nào. Việc ký GPG và tạo checksum là bên ngoài và chỉ được tham chiếu ở đây.

Tính phù hợp

Không có tuyên bố phù hợp tiêu chuẩn nào cho module này; đây là một lớp mô hình hóa bản phát hành, và NextPDF không giữ chứng nhận nào. Tên tệp SBOM mặc định (sbom-{version}.cdx.json) khớp với tài liệu CycloneDX mà trình sinh SBOM của core ghi ra; manifest tham chiếu bằng chứng đó và không xác thực nó. Chữ ký GPG và checksum được tạo ra và xác minh bởi pipeline phát hành bao quanh. Việc ghi lại một đường dẫn bằng chứng là năng lực, không phải chứng thực: một manifest tự nó không phải là bằng chứng, không chứng thực nguồn gốc, không chứng nhận một bản phát hành, và không cấu thành tư vấn pháp lý.

Ghi chú phát triển

Ưu tiên ReleaseManifest::createWithDefaults để các tên tệp bằng chứng luôn nhất quán với ArtifactNamer. Dành constructor thô cho các trường hợp ghi đè từng đường dẫn có chủ ý.
Chạy cả hai cổng validate() trong CI trước mọi bước phát hành và làm pipeline thất bại khi có danh sách lỗi không rỗng.
PublishingPlan::fromProfiles mặc định là PublishingEnvironment::Staging. Truyền Production một cách tường minh; không có gì trong module này thăng tiến một environment ngầm định.
Các manifest được tuần tự hóa mang các giá trị hậu thuẫn của enum (paid, encoded, ioncube, v.v.) và dấu thời gian ATOM; hãy xem các chuỗi đó là hợp đồng trên đường truyền.
Các artifact evaluation nằm trong một namespace gói riêng (hậu tố -evaluation). Giữ các registry paid và evaluation tách biệt trong cấu hình Composer của bạn.
Việc định tuyến theo từng kênh, thông tin xác thực, và lưu trữ là trách nhiệm của người vận hành. Kế hoạch cho bộ công cụ biết một artifact thuộc về đâu, không phải cách xác thực tới nó.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ thủ, bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.

Xem thêm

Release (trang năng lực)
Licensing — Tài liệu tham chiếu chuyên sâu — các enum LicenseEdition, LicenseChannel, và DeliveryMode mà các hồ sơ tiêu thụ.
Tổng quan Enterprise
Kích hoạt giấy phép