الإصدار — مرجع متعمّق

في لمحة

يُنمذج فضاء الأسماء NextPDF\Enterprise\Release إصدارَ المنتج بوصفه كائنات قيمة غير قابلة للتغيير ومُنمَّطة. يتكوّن سطحه العام من سبع فئات final وخمسة تعدادات مُسنَدة إلى سلاسل نصّية. تُجمِّع ReleaseManifest مُدخلات ArtifactManifest لكلّ منتج، إضافةً إلى مسارات أدلّة سلسلة التوريد. وBuildProfile هي المصدر الوحيد للحقيقة لمتغيّر منتج واحد. وتشتقّ ArtifactNamer وPackageMapping أسماء ملفّات حتمية وهويّة حزمة ⁨Composer⁩ من ملفّ تعريف. وتحلّ PublishingPlan::fromProfiles كلّ ملفّ تعريف إلى مُدخلات PublishingTarget مُنمَّطة بالقناة وحدّ الوصول الصحيحين. وتُنمِّط ReleaseStatus دورة حياة الإصدار. لا تُجري الوحدة أيّ إدخال/إخراج، ولا استدعاءات شبكية، ولا تعمية؛ إنها نمذجة بيانات وصفية صِرفة.

التوفّر والترخيص

تُشحن هذه الإمكانية في ⁨NextPDF Enterprise⁩ (nextpdf/enterprise) وتُفعَّل بمظروف ترخيص من فئة ⁨Enterprise⁩. النشرُ الذي لا يملك ذلك الاستحقاق لا يُحمِّل فئات الإمكانية. قارن بين الإصدارات واحصل على ترخيص.

يُرخَّص هذا السطح عبر حدود حزمة nextpdf/enterprise وليس له رمز إمكانية منفصل لكلّ ميزة. لا يشحن ⁨Core⁩ و⁨Pro⁩ طبقةَ نمذجة إصدارات.

سطح واجهة برمجة التطبيقات العامّة

composer require nextpdf/enterprise:^3

الرمز	المعامِلات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	يبني مستند الإصدار الأعلى غير القابل للتغيير	مثيل	—	final readonly؛ SCHEMA_VERSION هو '1.0'؛ رقم ثانوي للحقول الإضافية، ورقم رئيسي للتغييرات الكاسِرة؛ منذ 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	—	يتشارك المُرمَّز والنصّ الصريح اسمَ حزمة واحدًا؛ لكن عناوين ⁨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؛ الإنتاج دائمًا خيار صريح
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / لا شيء	مساعِدات تصفية وتعداد على الأهداف المحلولة	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames مُرتَّبة ومنزوعة التكرار
PublishingPlan::validate	لا شيء	يتحقّق من أن الأهداف غير فارغة، وأن الإصدارات تطابق الخطة، وألّا تقع أيّ حزمة تقييم في حدّ مدفوع	list<string> من الأخطاء؛ الفراغ يعني صحّة	لا يرمي أبدًا	شغّله قبل أيّ خطوة رفع
PublishingPlan::toArray	لا شيء	يُسَلسِل لمُخرجات التشغيل التجريبي والتسجيل	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⁩، والمجاميع التحقّقية). إصدار مخطّطها ثانوي-للإضافي ورئيسي-للكاسِر.
• BuildProfile هي المصدر الوحيد للحقيقة لما يحتويه المنتج وكيفية تحزيمه. تشتقّ التسمية والبيان والخطة جميعُها من ملفّ التعريف؛ لا يوجد مصدر تهيئة ثانوي.
• EncodingTechnology يُسمّي أداة الترميز؛ وDeliveryMode (من وحدة الترخيص) يُسمّي الشكل المُسلَّم. الاثنان منفصلان عمدًا، والمنتج بنصّ صريح يُبلِّغ دائمًا عن EncodingTechnology::None.
• DistributionChannel يفصل منشأ المنتج (تخزين ثنائي؛ وجهة الرفع) عن طبقة استهلاك الحزمة (السجلّ الذي يقرؤه composer require). يُخزّن المنشأ الثنائيَّ؛ وتقدّم طبقة الاستهلاك البياناتِ الوصفية التي تشير إليه.
• AccessBoundary يعدّد ⁨Paid⁩ و⁨Evaluation⁩ و⁨Internal⁩. كلّ حدّ يتطلّب استيثاقًا. تخدم المنتجات الداخلية ⁨CI⁩ و⁨QA⁩ والتشغيل التجريبي وليست مواجِهة للعملاء أبدًا.
• 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 إلى منشأ المنتج.
• منتجات الحدّ الداخلي ليست مواجِهة للعملاء أبدًا؛ وتوجيهها إلى قناة عملاء خطأ نمذجة صريح.
• لا تُجري هذه الوحدة أيّ عمليات تعمية. توقيع ⁨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⁩ لديك.
• التوجيه لكلّ قناة، وبيانات الاعتماد، والتخزين مسؤولية المُشغّل. تُخبر الخطةُ الأدواتِ بمكان انتماء المنتج، لا بكيفية الاستيثاق إليه.

حدود النشر

توثّق هذه الصفحة السلوكَ القابل للملاحظة خارجيًّا وسطحَ واجهة برمجة التطبيقات العامّة المدعوم فقط. مسارات فضاء الأسماء الداخلية، والفئات المساعِدة، وجداول الآليات، وأسماء ملفّات كتيّبات التشغيل، وبادئات التذاكر خارج النطاق.

اطّلع أيضًا

• الإصدار (صفحة الإمكانية)
• الترخيص — مرجع متعمّق — تعدادات LicenseEdition وLicenseChannel وDeliveryMode التي تستهلكها ملفّات التعريف.
• نظرة عامة على ⁨Enterprise⁩
• تفعيل الترخيص