Release — szczegółowa referencja

W skrócie

Przestrzeń nazw NextPDF\Enterprise\Release modeluje wydanie produktu jako niezmienne, typowane obiekty wartości. Jej publiczna powierzchnia to siedem klas final oraz pięć wyliczeń opartych na łańcuchach znaków. ReleaseManifest agreguje wpisy ArtifactManifest dla poszczególnych artefaktów oraz ścieżki dowodów łańcucha dostaw. BuildProfile jest jedynym źródłem prawdy dla jednego wariantu artefaktu. ArtifactNamer oraz PackageMapping wyprowadzają z profilu deterministyczne nazwy plików i tożsamość pakietu Composer. PublishingPlan::fromProfiles rozwiązuje każdy profil do typowanych wpisów PublishingTarget z właściwym kanałem i granicą dostępu. ReleaseStatus typuje cykl życia wydania. Moduł nie wykonuje operacji wejścia/wyjścia, nie wykonuje wywołań sieciowych ani kryptografii; to czyste modelowanie metadanych.

Dostępność i licencjonowanie

Ta funkcjonalność jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się w ramach koperty licencyjnej poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcjonalności. Porównaj edycje i uzyskaj licencję.

Ta powierzchnia jest licencjonowana granicą pakietu nextpdf/enterprise i nie ma osobnego kodu funkcjonalności dla poszczególnych funkcji. Core i Pro nie dostarczają warstwy modelowania wydań.

Powierzchnia publicznego API

composer require nextpdf/enterprise:^3

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem	Uwagi
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	Buduje niezmienny dokument wydania najwyższego poziomu	instancja	—	final readonly; SCHEMA_VERSION to '1.0'; minor dla pól dodatkowych, major dla zmian łamiących; od 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	Wstępnie konfiguruje domyślne nazwy plików SBOM, podpisu i sumy kontrolnej za pomocą ArtifactNamer	self	—	Kanoniczny punkt wejścia dla budowniczych wydań; użyj konstruktora, aby nadpisać poszczególne ścieżki
ReleaseManifest::toArray / ::toJson	brak	Serializuje manifest ze wszystkimi wpisami artefaktów	array / łańcuch JSON	toJson: JsonException przy niepowodzeniu kodowania	Sformatowane czytelnie, bez ucieczkowania ukośników; built_at w formacie ATOM
ReleaseManifest::validate	brak	Sprawdza, czy lista artefaktów jest niepusta i czy każdy artefakt jest zgodny z wersją i commitem wydania	list<string> błędów; pusta oznacza poprawność	Nigdy nie zgłasza wyjątku	Wywołujący muszą traktować niepustą listę jako defekt
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	Rejestruje jeden zbudowany artefakt: co zbudowano, jak i jak to zweryfikować	instancja	—	final readonly; ioncubeExpire to null dla artefaktów bez terminu wygaśnięcia
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	Wyprowadza nazwę pliku oraz wszystkie wymiary profilu	self	—	builtAt domyślnie przyjmuje bieżący czas
ArtifactManifest::toArray	brak	Serializuje do kodowania JSON	array<string, string|null>	—	Pola wyliczeń serializują się do swoich bazowych wartości łańcuchowych
BuildProfile::__construct / ::fromArray	pola profilu / array $data	Definiuje jeden wariant artefaktu; jedyne źródło prawdy dla nazewnictwa, manifestu i planu	instancja / self	fromArray: InvalidArgumentException przy brakującym lub pustym polu wymaganym	Klucze wymagane: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	brak	Pomocnicze predykaty nad wymiarami profilu	bool	—	Kodowanie wymaga jednoczesnego DeliveryMode::Encoded oraz EncodingTechnology::IonCube
ArtifactNamer::format	BuildProfile $profile, string $version	Emituje nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip	non-empty-string	—	Deterministyczny; kropki są usuwane z docelowej wersji PHP (8.4 staje się php84)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile: brak)	Emituje SHA256SUMS-{v}.txt, SHA256SUMS-{v}.txt.asc, sbom-{v}.cdx.json, release-manifest.json	non-empty-string	—	Nazwa pliku SBOM odpowiada dokumentowi CycloneDX zapisywanemu przez generator SBOM w Core
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	Mapuje na nextpdf/pro lub nextpdf/enterprise; kanał ewaluacyjny dopisuje -evaluation	non-empty-string	InvalidArgumentException przy nieznanej edycji	Osobna przestrzeń nazw ewaluacji zapobiega mieszaniu z płatnymi artefaktami
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	Rozwiązuje adres URL pobierania artefaktu w kanonicznym repozytorium artefaktów	non-empty-string	—	Wersja kodowana i jawnotekstowa dzielą nazwę pakietu; ich adresy URL dystrybucji się różnią
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / brak / brak / brak	Granica podąża za kanałem licencji; stałe kanały źródła i konsumpcji; wszystkie nazwy pakietów udostępnianych klientowi	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core nie jest pakietem premium i jest wykluczony z listy nazw
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	Rozwiązuje dwa cele na profil: jedno źródło artefaktu, jedna warstwa konsumpcji	self	—	Środowisko domyślnie przyjmuje Staging; produkcja jest zawsze jawnym wyborem
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / brak	Pomocnicze filtry i wyliczenia nad rozwiązanymi celami	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames jest posortowana i pozbawiona duplikatów
PublishingPlan::validate	brak	Sprawdza, czy cele są niepuste, czy wersje są zgodne z planem i czy żaden pakiet ewaluacyjny nie znajduje się w granicy płatnej	list<string> błędów; pusta oznacza poprawność	Nigdy nie zgłasza wyjątku	Uruchom przed każdym krokiem przesyłania
PublishingPlan::toArray	brak	Serializuje na potrzeby wyniku dry-run i logowania	array<string, mixed>	—	Zawiera target_count oraz listę pakietów
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	Rozwiązuje nazwę pakietu, granicę dostępu i nazwę pliku artefaktu dla jednego kanału	self	—	final readonly; toArray serializuje na potrzeby logowania
AccessBoundary	wyliczenie: Paid, Evaluation, Internal	isCustomerFacing ma wartość true tylko dla Paid i Evaluation	oparte na 'paid', 'evaluation', 'internal'	—	requiresAuthentication zwraca true dla każdej granicy
DistributionChannel	wyliczenie: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin i isConsumptionLayer rozdzielają dwie role	oparte na 'github_releases', 'private_packagist', 'direct_download'	—	DirectDownload jest zarezerwowany dla przyszłego kanału z podpisanymi adresami URL
EncodingTechnology	wyliczenie: IonCube, None	Nazywa narzędzie kodowania, odrębne od formy dostarczania	oparte na 'ioncube', 'none'	—	Artefakt jawnotekstowy zawsze zgłasza None
PublishingEnvironment	wyliczenie: Staging, Production	isCustomerFacing ma wartość true tylko dla Production	oparte na 'staging', 'production'	—	Staging jest wewnętrznym celem weryfikacji
ReleaseStatus	wyliczenie: Built, Audited, Staged, Published, Revoked, Superseded	canPromote, nextStatus, isCustomerVisible, isTerminal typują cykl życia	nextStatus zwraca ?self	—	Łańcuch promocji Built → Audited → Staged → Published; Revoked i Superseded są terminalne

Sygnatury punktów wejścia, dosłownie ze źródła:

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

Kontrakt zachowania

• Każda klasa jest final; każda klasa wartości jest readonly. Konstrukcja ustala cały stan. Moduł nie wykonuje żadnych operacji na systemie plików, sieciowych ani kryptograficznych.
• ReleaseManifest to niezmienny dokument najwyższego poziomu dla danej wersji: wersja semantyczna, commit źródłowy, znacznik czasu kompilacji, lista artefaktów oraz opcjonalne ścieżki dowodów łańcucha dostaw (SBOM, podpis GPG, sumy kontrolne). Wersja jego schematu jest minor dla dodatków i major dla zmian łamiących.
• BuildProfile jest jedynym źródłem prawdy dla tego, co zawiera artefakt i jak jest pakowany. Nazewnictwo, manifest i plan — wszystkie wyprowadzają się z profilu; nie ma wtórnego źródła konfiguracji.
• EncodingTechnology nazywa narzędzie kodowania; DeliveryMode (z modułu Licensing) nazywa dostarczoną formę. Te dwa pojęcia są celowo rozdzielone, a artefakt jawnotekstowy zawsze zgłasza EncodingTechnology::None.
• DistributionChannel oddziela źródło artefaktu (magazyn binariów; miejsce docelowe przesyłania) od warstwy konsumpcji pakietu (rejestru, który odczytuje composer require). Źródło przechowuje binarium; warstwa konsumpcji udostępnia metadane, które na nie wskazują.
• AccessBoundary wylicza Paid, Evaluation oraz Internal. Każda granica wymaga uwierzytelnienia. Artefakty Internal obsługują CI, QA i staging i nigdy nie są udostępniane klientowi.
• PublishingPlan::fromProfiles rozwiązuje każdy profil do dokładnie dwóch celów: celu źródła artefaktu i celu warstwy konsumpcji, z granicą dostępu wyprowadzoną z kanału licencji profilu, dzięki czemu artefakty płatne i ewaluacyjne są kierowane prawidłowo.
• Plan opisuje zamierzone cele, a nie transport. Faktyczne przesłanie wykonuje otaczające narzędzia wydania, a manifest rejestruje — lecz sam nie wytwarza — dowody łańcucha dostaw.
• ReleaseStatus typuje cykl życia: Built → Audited → Staged → Published, z Revoked i Superseded jako terminalnymi wyjściami z Published. Tylko Published jest widoczny dla klienta; canPromote ma wartość false od Published w górę.
• ReleaseManifest::validate oraz PublishingPlan::validate zgłaszają błędy spójności jako listy łańcuchów znaków i nigdy nie zgłaszają wyjątku. Pusta lista jest jedynym poprawnym wynikiem.

Przypadki brzegowe i tryby awarii

• BuildProfile::fromArray z brakującym, nie będącym łańcuchem lub pustym polem wymaganym: InvalidArgumentException nazywający to pole.
• BuildProfile::fromArray z pustym lub nie będącym łańcuchem ioncube_expire: normalizowany do null (bez wygaśnięcia). Wpisy w encode_paths i exclude_paths, które nie są łańcuchami lub są puste, są po cichu odrzucane.
• PackageMapping::resolvePackageName z edycją spoza znanej mapy: InvalidArgumentException.
• ReleaseManifest::toJson na danych niemożliwych do zakodowania: JsonException. Serializacja używa JSON_THROW_ON_ERROR; nie ma cichego zachowania awaryjnego.
• ReleaseManifest::validate zgłasza jako błędy pustą listę artefaktów oraz każdy artefakt, którego wersja lub commit źródłowy różni się od wydania.
• PublishingPlan::validate zgłasza pustą listę celów, każdą wersję celu odbiegającą od planu oraz każdy pakiet ewaluacyjny rozwiązany do granicy płatnej.
• ReleaseStatus::nextStatus zwraca null z Published, Revoked i Superseded. Wywołujący muszą obsłużyć null; nie ma zawijania.
• Kanały źródła i warstwy konsumpcji są odrębne; nie kieruj composer require na źródło artefaktu.
• Artefakty z granicy Internal nigdy nie są udostępniane klientowi; ich skierowanie do kanału klienta to jawny błąd modelowania.
• Ten moduł nie wykonuje żadnych operacji kryptograficznych. Podpisywanie GPG i generowanie sum kontrolnych są zewnętrzne i tutaj jedynie przywoływane.

Zgodność

Dla tego modułu nie deklaruje się żadnej zgodności ze standardami; to warstwa modelowania wydań, a NextPDF nie posiada żadnej certyfikacji. Domyślna nazwa pliku SBOM (sbom-{version}.cdx.json) odpowiada dokumentowi CycloneDX zapisywanemu przez generator SBOM w Core; manifest odwołuje się do tego dowodu i go nie waliduje. Podpisy GPG i sumy kontrolne są wytwarzane i weryfikowane przez otaczający potok wydania. Zarejestrowanie ścieżki dowodu jest funkcjonalnością, a nie poświadczeniem: manifest sam w sobie nie jest dowodem, nie poświadcza pochodzenia, nie certyfikuje wydania ani nie stanowi porady prawnej.

Uwagi deweloperskie

• Preferuj ReleaseManifest::createWithDefaults, aby nazwy plików dowodów zawsze zgadzały się z ArtifactNamer. Zarezerwuj surowy konstruktor na celowe nadpisania poszczególnych ścieżek.
• Uruchamiaj obie bramki validate() w CI przed każdym krokiem publikacji i przerywaj potok przy niepustej liście błędów.
• PublishingPlan::fromProfiles domyślnie przyjmuje PublishingEnvironment::Staging. Przekaż Production jawnie; nic w tym module nie promuje środowiska w sposób niejawny.
• Serializowane manifesty niosą bazowe wartości wyliczeń (paid, encoded, ioncube itd.) oraz znaczniki czasu ATOM; traktuj te łańcuchy jako kontrakt transmisyjny.
• Artefakty ewaluacyjne żyją w osobnej przestrzeni nazw pakietu (sufiks -evaluation). Utrzymuj rejestry płatne i ewaluacyjne rozdzielone w konfiguracji Composer.
• Kierowanie dla poszczególnych kanałów, poświadczenia i przechowywanie należą do obowiązków operatora. Plan mówi narzędziom, gdzie należy artefakt, a nie jak się do niego uwierzytelnić.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Zobacz też

• Release (strona funkcjonalności)
• Licensing — szczegółowa referencja — wyliczenia LicenseEdition, LicenseChannel oraz DeliveryMode, których używają profile.
• Przegląd Enterprise
• Aktywacja licencji