Release — เอกสารอ้างอิงเชิงลึก

โดยสรุป

เนมสเปซ NextPDF\Enterprise\Release สร้างแบบจำลอง product release เป็น value object แบบมีชนิดที่ไม่เปลี่ยนแปลง พื้นผิวสาธารณะประกอบด้วยคลาส final เจ็ดคลาสและ enum ที่มีค่ารองรับเป็น string ห้าตัว ReleaseManifest รวม ArtifactManifest ต่ออาร์ทิแฟกต์เข้าด้วยกันพร้อมเส้นทางหลักฐาน supply-chain BuildProfile เป็นแหล่งความจริงเพียงหนึ่งเดียวสำหรับอาร์ทิแฟกต์รูปแบบหนึ่ง ArtifactNamer และ PackageMapping ได้มาซึ่งชื่อไฟล์แบบกำหนดผลได้แน่นอนและ identity ของแพ็กเกจ Composer จากโปรไฟล์ PublishingPlan::fromProfiles resolve ทุกโปรไฟล์ไปยัง PublishingTarget แบบมีชนิดพร้อมช่องทางและขอบเขตการเข้าถึงที่ถูกต้อง ReleaseStatus กำหนดชนิดของวงจรชีวิต release โมดูลนี้ไม่ทำ I/O ไม่เรียกเครือข่าย และไม่เข้ารหัสลับ เป็นการสร้างแบบจำลองเมทาดาทาล้วน

ความพร้อมใช้งานและสิทธิ์การใช้งาน

ความสามารถนี้มาพร้อมกับ NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วย license envelope ระดับ Enterprise การติดตั้งที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอรับสิทธิ์การใช้งาน

พื้นผิวนี้ได้รับสิทธิ์ตามขอบเขตของแพ็กเกจ nextpdf/enterprise และไม่มีรหัสความสามารถต่อฟีเจอร์แยกต่างหาก Core และ Pro ไม่ได้มาพร้อมเลเยอร์การสร้างแบบจำลอง release

พื้นผิว API สาธารณะ

composer require nextpdf/enterprise:^3

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	สร้างเอกสาร release ระดับบนสุดที่ไม่เปลี่ยนแปลง	instance	—	final readonly; SCHEMA_VERSION เป็น '1.0'; minor สำหรับฟิลด์เพิ่มเติม major สำหรับการเปลี่ยนที่ทำลายความเข้ากันได้; ตั้งแต่ 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	ตั้งค่าล่วงหน้าให้ชื่อไฟล์ SBOM ลายเซ็น และ checksum เริ่มต้นผ่าน ArtifactNamer	self	—	จุดเข้าใช้งานหลักสำหรับผู้สร้าง release; ใช้ constructor เพื่อแทนที่เส้นทางแต่ละรายการ
ReleaseManifest::toArray / ::toJson	none	serialize manifest พร้อมรายการอาร์ทิแฟกต์ทั้งหมด	array / JSON string	toJson: JsonException เมื่อการเข้ารหัสล้มเหลว	จัดรูปแบบสวยงาม ไม่ escape เครื่องหมายทับ; built_at ในรูปแบบ ATOM
ReleaseManifest::validate	none	ตรวจว่ารายการอาร์ทิแฟกต์ไม่ว่าง และทุกอาร์ทิแฟกต์ตรงกับเวอร์ชันและ commit ของ release	list<string> ของข้อผิดพลาด; ว่างหมายถึงถูกต้อง	ไม่โยนข้อผิดพลาด	ผู้เรียกต้องถือว่ารายการที่ไม่ว่างคือข้อบกพร่อง
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	บันทึกอาร์ทิแฟกต์ที่สร้างหนึ่งรายการ: สร้างอะไร สร้างอย่างไร และตรวจสอบอย่างไร	instance	—	final readonly; ioncubeExpire เป็น null สำหรับอาร์ทิแฟกต์ที่ไม่หมดอายุ
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	ได้มาซึ่งชื่อไฟล์และทุกมิติของโปรไฟล์	self	—	builtAt ค่าเริ่มต้นเป็นเวลาปัจจุบัน
ArtifactManifest::toArray	none	serialize สำหรับการเข้ารหัส JSON	array<string, string|null>	—	ฟิลด์ enum serialize เป็นค่า string ที่รองรับ
BuildProfile::__construct / ::fromArray	ฟิลด์ของโปรไฟล์ / array $data	นิยามอาร์ทิแฟกต์รูปแบบหนึ่ง; แหล่งความจริงเพียงหนึ่งเดียวสำหรับการตั้งชื่อ manifest และแผน	instance / self	fromArray: InvalidArgumentException เมื่อฟิลด์ที่จำเป็นขาดหายหรือว่าง	คีย์ที่จำเป็น: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	none	ตัวช่วยเชิงพรีดิเคตเหนือมิติของโปรไฟล์	bool	—	การเข้ารหัสต้องมีทั้ง DeliveryMode::Encoded และ EncodingTechnology::IonCube ร่วมกัน
ArtifactNamer::format	BuildProfile $profile, string $version	สร้าง nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip	non-empty-string	—	กำหนดผลได้แน่นอน; จุดถูกตัดออกจาก PHP target (8.4 กลายเป็น php84)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile: none)	สร้าง 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 ต่อท้ายด้วย -evaluation	non-empty-string	InvalidArgumentException เมื่อรุ่นไม่รู้จัก	เนมสเปซ evaluation ที่แยกต่างหากป้องกันการปนกับอาร์ทิแฟกต์ที่ชำระเงิน
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	resolve URL ดาวน์โหลดอาร์ทิแฟกต์บน repository อาร์ทิแฟกต์หลัก	non-empty-string	—	แบบ Encoded และ cleartext ใช้ชื่อแพ็กเกจร่วมกัน แต่ dist URL ต่างกัน
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / none / none / none	ขอบเขตตามช่องทาง license; origin และ consumption channel คงที่; ชื่อแพ็กเกจที่ลูกค้าเห็นทั้งหมด	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core ไม่ใช่แพ็กเกจ premium และถูกกันออกจากรายชื่อ
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	resolve สองเป้าหมายต่อโปรไฟล์: artifact origin หนึ่ง consumption layer หนึ่ง	self	—	environment ค่าเริ่มต้นเป็น Staging; production เป็นตัวเลือกที่ชัดเจนเสมอ
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / none	ตัวช่วยกรองและแจกแจงเหนือเป้าหมายที่ resolve แล้ว	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames ถูกเรียงและกำจัดรายการซ้ำ
PublishingPlan::validate	none	ตรวจว่าเป้าหมายไม่ว่าง เวอร์ชันตรงกับแผน และไม่มีแพ็กเกจ evaluation อยู่ในขอบเขตที่ชำระเงิน	list<string> ของข้อผิดพลาด; ว่างหมายถึงถูกต้อง	ไม่โยนข้อผิดพลาด	รันก่อนขั้นตอนการอัปโหลดใด ๆ
PublishingPlan::toArray	none	serialize สำหรับผลลัพธ์ dry-run และการบันทึก log	array<string, mixed>	—	รวม target_count และรายชื่อแพ็กเกจ
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	resolve ชื่อแพ็กเกจ ขอบเขตการเข้าถึง และชื่อไฟล์อาร์ทิแฟกต์สำหรับหนึ่งช่องทาง	self	—	final readonly; toArray serialize สำหรับการบันทึก log
AccessBoundary	enum: Paid, Evaluation, Internal	isCustomerFacing เป็น true สำหรับ Paid และ Evaluation เท่านั้น	รองรับด้วย 'paid', 'evaluation', 'internal'	—	requiresAuthentication คืน true สำหรับทุกขอบเขต
DistributionChannel	enum: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin และ isConsumptionLayer แยกสองบทบาท	รองรับด้วย 'github_releases', 'private_packagist', 'direct_download'	—	DirectDownload สงวนไว้สำหรับช่องทาง signed-URL ในอนาคต
EncodingTechnology	enum: IonCube, None	ตั้งชื่อเครื่องมือเข้ารหัส แยกจากรูปแบบการส่งมอบ	รองรับด้วย 'ioncube', 'none'	—	อาร์ทิแฟกต์แบบ cleartext รายงานเป็น None เสมอ
PublishingEnvironment	enum: Staging, Production	isCustomerFacing เป็น true เฉพาะ Production	รองรับด้วย 'staging', 'production'	—	Staging เป็นเป้าหมายการตรวจสอบภายใน
ReleaseStatus	enum: 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; ทุก value class เป็น readonly การสร้างกำหนดสถานะทั้งหมดคงที่ โมดูลนี้ไม่ดำเนินการกับ filesystem เครือข่าย หรือการเข้ารหัสลับ
• ReleaseManifest เป็นเอกสารระดับบนสุดที่ไม่เปลี่ยนแปลงสำหรับเวอร์ชันหนึ่ง: semantic version, source commit, build timestamp, รายการอาร์ทิแฟกต์ และเส้นทางหลักฐาน supply-chain ที่ไม่บังคับ (SBOM, GPG signature, checksums) เวอร์ชันสคีมาของมันเป็น minor สำหรับฟิลด์เพิ่มเติม และ major สำหรับการเปลี่ยนที่ทำลายความเข้ากันได้
• BuildProfile เป็นแหล่งความจริงเพียงหนึ่งเดียวสำหรับสิ่งที่อาร์ทิแฟกต์บรรจุและวิธีบรรจุ การตั้งชื่อ manifest และแผนทั้งหมดได้มาจากโปรไฟล์ ไม่มีแหล่งการตั้งค่ารอง
• EncodingTechnology ตั้งชื่อเครื่องมือเข้ารหัส; DeliveryMode (จากโมดูล Licensing) ตั้งชื่อรูปแบบที่ส่งมอบ ทั้งสองแยกจากกันโดยตั้งใจ และอาร์ทิแฟกต์แบบ cleartext รายงานเป็น EncodingTechnology::None เสมอ
• DistributionChannel แยก artifact origin (binary storage; ปลายทางที่อัปโหลด) ออกจาก package consumption layer (registry ที่ composer require อ่าน) origin เก็บไบนารี; consumption layer ให้บริการเมทาดาทาที่ชี้ไปยังไบนารีนั้น
• AccessBoundary แจกแจง Paid, Evaluation และ Internal ทุกขอบเขตต้องมีการตรวจสอบสิทธิ์ อาร์ทิแฟกต์ Internal ให้บริการ CI, QA และ staging และไม่เผยแพร่ต่อลูกค้าเลย
• PublishingPlan::fromProfiles resolve แต่ละโปรไฟล์ไปยังสองเป้าหมายพอดี: เป้าหมาย artifact-origin หนึ่งและเป้าหมาย consumption-layer หนึ่ง โดยขอบเขตการเข้าถึงได้มาจากช่องทาง license ของโปรไฟล์ เพื่อให้อาร์ทิแฟกต์ paid และ evaluation ถูกกำหนดเส้นทางอย่างถูกต้อง
• แผนอธิบายเป้าหมายที่ตั้งใจไว้ ไม่ใช่การขนส่ง การอัปโหลดจริงดำเนินการโดยเครื่องมือ release ที่อยู่รอบ ๆ และ manifest บันทึก — แต่ไม่ได้สร้างเอง — หลักฐาน supply-chain
• ReleaseStatus กำหนดชนิดของวงจรชีวิต: Built → Audited → Staged → Published โดยมี Revoked และ Superseded เป็นทางออกสิ้นสุดจาก Published มีเพียง Published เท่านั้นที่ลูกค้ามองเห็น; canPromote เป็น false ตั้งแต่ Published เป็นต้นไป
• ReleaseManifest::validate และ PublishingPlan::validate รายงานข้อผิดพลาดความสอดคล้องเป็นรายการ string และไม่โยนข้อผิดพลาด รายการว่างเป็นผลลัพธ์ที่ถูกต้องเพียงอย่างเดียว

กรณีขอบและโหมดความล้มเหลว

• BuildProfile::fromArray เมื่อฟิลด์ที่จำเป็นขาดหาย ไม่ใช่ string หรือว่าง: InvalidArgumentException ที่ระบุชื่อฟิลด์
• BuildProfile::fromArray เมื่อ ioncube_expire ว่างหรือไม่ใช่ string: ปรับให้เป็น null (ไม่หมดอายุ) รายการที่ไม่ใช่ string หรือว่างใน encode_paths และ exclude_paths ถูกทิ้งเงียบ ๆ
• PackageMapping::resolvePackageName เมื่อรุ่นอยู่นอกแผนที่ที่รู้จัก: InvalidArgumentException
• ReleaseManifest::toJson เมื่อข้อมูลเข้ารหัสไม่ได้: JsonException การ serialize ใช้ JSON_THROW_ON_ERROR; ไม่มี fallback แบบเงียบ
• ReleaseManifest::validate รายงานรายการอาร์ทิแฟกต์ว่าง และอาร์ทิแฟกต์ใดที่เวอร์ชันหรือ source commit ต่างจาก release เป็นข้อผิดพลาด
• PublishingPlan::validate รายงานรายการเป้าหมายว่าง เป้าหมายใดที่เวอร์ชันเบี่ยงเบนจากแผน และแพ็กเกจ evaluation ใดที่ resolve เข้าไปในขอบเขตที่ชำระเงิน
• ReleaseStatus::nextStatus คืน null จาก Published, Revoked และ Superseded ผู้เรียกต้องจัดการกับ null; ไม่มีการวนกลับ
• ช่องทาง origin และ consumption-layer แยกจากกัน อย่าชี้ composer require ไปยัง artifact origin
• อาร์ทิแฟกต์ขอบเขต Internal ไม่เผยแพร่ต่อลูกค้าเลย การกำหนดเส้นทางไปยังช่องทางลูกค้าเป็นข้อผิดพลาดเชิงการสร้างแบบจำลองที่ชัดเจน
• โมดูลนี้ไม่ดำเนินการทางการเข้ารหัสลับใด ๆ การลงนาม GPG และการสร้าง checksum เป็นภายนอกและถูกอ้างอิงในที่นี้เท่านั้น

ความสอดคล้อง

ไม่มีการอ้างความสอดคล้องกับมาตรฐานสำหรับโมดูลนี้ เป็นเลเยอร์การสร้างแบบจำลอง release และ NextPDF ไม่ถือใบรับรองใด ชื่อไฟล์ SBOM เริ่มต้น (sbom-{version}.cdx.json) ตรงกับเอกสาร CycloneDX ที่ตัวสร้าง SBOM ของ core เขียน; manifest อ้างอิงหลักฐานนั้นและไม่ตรวจสอบมัน ลายเซ็น GPG และ checksum ถูกสร้างและตรวจสอบโดย release pipeline ที่อยู่รอบ ๆ การบันทึกเส้นทางหลักฐานคือความสามารถ ไม่ใช่การรับรอง: manifest ไม่ใช่หลักฐานในตัวเอง ไม่รับรองที่มา ไม่ออกใบรับรอง release และไม่ใช่คำแนะนำทางกฎหมาย

บันทึกการพัฒนา

• ควรใช้ ReleaseManifest::createWithDefaults เพื่อให้ชื่อไฟล์หลักฐานสอดคล้องกับ ArtifactNamer เสมอ สงวน constructor แบบดิบไว้สำหรับการแทนที่ต่อเส้นทางโดยตั้งใจ
• รันทั้งสองเกต validate() ใน CI ก่อนขั้นตอนการเผยแพร่ใด ๆ และทำให้ pipeline ล้มเหลวเมื่อรายการข้อผิดพลาดไม่ว่าง
• PublishingPlan::fromProfiles ค่าเริ่มต้นเป็น PublishingEnvironment::Staging ส่ง Production อย่างชัดเจน; ไม่มีสิ่งใดในโมดูลนี้เลื่อน environment โดยปริยาย
• manifest ที่ serialize แล้วพก enum backing value (paid, encoded, ioncube และอื่น ๆ) และ ATOM timestamp; ถือ string เหล่านั้นเป็น wire contract
• อาร์ทิแฟกต์ evaluation อยู่ในเนมสเปซแพ็กเกจแยกต่างหาก (ต่อท้าย -evaluation) เก็บ registry ของ paid และ evaluation แยกจากกันในการตั้งค่า Composer ของคุณ
• การกำหนดเส้นทางต่อช่องทาง ข้อมูลรับรอง และการจัดเก็บเป็นความรับผิดชอบของผู้ดำเนินการ แผนบอกเครื่องมือว่าอาร์ทิแฟกต์อยู่ที่ใด ไม่ใช่วิธีตรวจสอบสิทธิ์เข้าถึง

ขอบเขตการเผยแพร่

หน้านี้อธิบายพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ดูเพิ่มเติม

• Release (หน้าความสามารถ)
• Licensing — เอกสารอ้างอิงเชิงลึก — enum LicenseEdition, LicenseChannel และ DeliveryMode ที่โปรไฟล์ใช้
• ภาพรวมของ Enterprise
• การเปิดใช้งานสิทธิ์การใช้งาน