قواعد استقرار SPI

لمحة سريعة

تتّبع واجهة مزوّد الخدمة في ⁨NextPDF⁩ الإصدار الدلالي (⁨Semantic Versioning⁩). يحمل كل عقد عام وسم @stability ووعدًا بالتوافق مع الإصدارات السابقة. استخدم هذه القواعد لتحديد العقود التي يمكنك الاعتماد عليها بأمان.

التثبيت

composer require nextpdf/core:^3

نظرة مفاهيمية عامة

تتضمّن واجهة مزوّد الخدمة العقود العامة في مساحتي الأسماء NextPDF\Contracts وNextPDF\Event. لا يُعدّ النوع جزءًا من الواجهة إلا إذا حمل تعليق ⁨PHPDoc⁩ في مصدره وسم @stability. هذا الوسم هو ما يحدّد الحدود. أما النوع الذي لا يحمل الوسم فهو نوع داخلي، حتى لو كشفه ⁨PHP⁩ بوصفه public.

يتّبع ⁨NextPDF⁩ الإصدار الدلالي (⁨Semantic Versioning⁩) 2.0.0. يتطلّب أي تغيير كاسر في عقد stable زيادة في الإصدار الرئيسي. أما العقد الجديد أو الإضافة غير الكاسرة فيزيدان الإصدار الفرعي. ويزيد إصلاح الخطأ إصدار التصحيح.

وسم ‎@⁨stability⁩

يعلن كل عقد عن واحدة من ثلاث قيم للاستقرار:

الوسم	المعنى	قاعدة التغيير
stable	جاهز للإنتاج وآمن للاعتماد عليه.	لا تغيير كاسر في إصدار فرعي أو إصدار تصحيح. لا تُضاف الطرائق الجديدة إلا بسلوك افتراضي أو في عقد جديد.
experimental	قابل للاستخدام، لكنه لم يُجمَّد بعد.	قد تتغيّر الواجهة في إصدار فرعي، مع إشعار إهمال مسبق.
deprecated	مجدول للإزالة.	يذكر العقد البديل وإصدار الإزالة.

يسجّل ⁨NextPDF⁩ الوعد الخاص بكل عقد في خريطة العقود المُولَّدة، ويعيد توليدها من المصدر في كل إصدار. يقدّم نص الوعد القاعدة الدقيقة لذلك العقد. تعامل مع تعليق ⁨PHPDoc⁩ في مصدر العقد بوصفه المصدر الوحيد للحقيقة.

فئات وعد التوافق مع الإصدارات السابقة

تسجّل خريطة العقود كل وعد ضمن واحدة من أربع فئات:

1. وعد الواجهة. “لا تغيير كاسر في إصدار فرعي أو إصدار تصحيح. لا طرائق جديدة إلا بتطبيق افتراضي.” ينطبق على معظم واجهات stable، بما في ذلك FontRegistryInterface وSignerInterface وHsmSignerInterface وHtmlSecurityPolicyInterface.
2. وعد التعداد. “لا إزالة للحالات. قد تُضاف حالات جديدة في إصدار فرعي.” ينطبق على تعدادات stable مثل Alignment وOrientation وOutputDestination.
3. وعد كائن القيمة المجمَّد. “توقيع المنشئ والخصائص العامة مجمَّدة. قد تُضاف طرائق جديدة.” ينطبق على كائنات القيمة مثل TextPreprocessResult وTextSegment، وعلى حمولات الأحداث المرتبطة بها.
4. الوعد التجريبي. “قد تتغيّر الواجهة في إصدار فرعي مع إشعار إهمال.” ينطبق على العقود experimental مثل DeferredSignerInterface وTimestampProviderInterface وCursorInterface وStreamingWriterInterface.

يجمّد الصنف final مثل EventDispatcher أو ListenerProvider توقيعات طرائقه العامة. استخدم التركيب لتوسيع صنف final. لا تشتقّ منه صنفًا فرعيًا.

عقود التدفق التجريبية

CursorInterface وStreamingWriterInterface عقدان experimental (منذ 3.1.0). يوفّر ⁨NextPDF⁩ تطبيقات محرّك نهائية ومختبَرة لكلا العقدين؛ وأصناف التطبيق داخلية وليست جزءًا من السطح العام. استهلك سلوك التدفق عبر العقد experimental العام. في معظم الحالات، لا تطبّق العقد بنفسك.

لأن العقد experimental، فقد يتغيّر توقيعه في إصدار فرعي، مع إشعار إهمال مسبق (الوعد التجريبي). ثبّت الإصدار بإحكام أو غلّفه خلف مُهايئ خاص بك قبل الاعتماد عليه في الإنتاج. تعامل مع عقد التدفق بوصفه نقطة توسعة قيد الاستقرار، لا نقطة مجمَّدة.

سطح ⁨API⁩

لا توجد في هذه الصفحة واجهة برمجة تطبيقات (⁨API⁩) في وقت التشغيل. السطح المعني هو وسم ⁨PHPDoc⁩ المسمّى @stability على كل عقد عام، وخريطة العقود المُعاد توليدها التي تجمع الوعد الخاص بكل عقد.

مثال برمجي — بداية سريعة

اقرأ استقرار العقد من المصدر قبل أن تعتمد عليه.

<?php

declare(strict_types=1);

use ReflectionClass;

$doc = (new ReflectionClass(\NextPDF\Contracts\FontRegistryInterface::class))
    ->getDocComment();

// Look for the "@stability stable" line in the contract PHPDoc.
\assert(\is_string($doc) && \str_contains($doc, '@stability stable'));

مثال برمجي — الإنتاج

يثبّت قيد إصدار ⁨Composer⁩ الإصدار الرئيسي، فهو الموضع الذي تحدث فيه التغييرات الكاسرة لعقد stable.

{
    "require": {
        "nextpdf/core": "^3.0"
    }
}

استخدم ^3.0 لتلقّي الإصدارات الفرعية وإصدارات التصحيح من دون أي تغيير كاسر في أي عقد stable. ثبّت الإصدار بإحكام أكبر عند الاعتماد على عقد experimental، لأن العقد experimental قد يتغيّر في إصدار فرعي.

الحالات الحدّية والمزالق

• الوسم، لا إمكانية الوصول. أي طريقة ⁨PHP⁩ موسومة بـ public لا تُعد جزءًا من واجهة مزوّد الخدمة ما لم يحمل النوع المعلِن عنها وسم @stability.
• انحراف العقود التجريبية. قد يتغيّر العقد experimental في إصدار فرعي. ثبّت الإصدار بإحكام أو غلّفه خلف مُهايئ خاص بك. ينطبق هذا على عقود التدفق حتى إذا كانت لها تطبيقات مشحونة.
• طرائق افتراضية جديدة. قد تكتسب واجهة stable طريقة لها سلوك افتراضي. طبّق الطريقة الجديدة عند الترقية كي يبقى تطبيقك الخاص صريحًا.
• تكافؤ الإصدارات. يتّبع ⁨NextPDF Pro⁩ و⁨NextPDF Enterprise⁩ القواعد نفسها. يظل العقد الذي تستهدفه في ⁨Core⁩ صالحًا أمام تطبيق ⁨Premium⁩ للعقد نفسه.

دورة حياة الإهمال

يمرّ العقد بدورة حياة محدّدة:

1. التمييز. يضبط المالك @stability deprecated في تعليق ⁨PHPDoc⁩ بالمصدر، ويسجّل البديل وإصدار الإزالة.
2. الإشعار. يُعلَن عن الإهمال في سجل التغييرات الخاص بالإصدار الذي ميّزه.
3. التداخل. يتعايش العقد المهمَل وبديله طوال إصدار فرعي واحد على الأقل.
4. الإزالة. يُزال العقد في الإصدار الرئيسي المذكور. لا تحدث الإزالة أبدًا في إصدار فرعي أو إصدار تصحيح.

خطّط للترقية فور تمييز عقد بأنه deprecated. يُذكَر البديل دائمًا.

الأداء

تحدّد هذه الصفحة سياسة فقط. ولا تترتب عليها أي تكلفة في وقت التشغيل.

ملاحظات أمنية

عقود التوقيع stable وتتّبع وعد الواجهة. لا تصل أي طريقة جديدة إلى عقد توقيع إلا بسلوك افتراضي أو في عقد جديد، لذلك لا ينكسر التطبيق المدعوم بالعتاد عند ترقية فرعية. راجع سجل التغييرات قبل أي ترقية رئيسية، لأن الإصدار الرئيسي قد يغيّر عقدًا stable.

المطابقة

تطابق قواعد إدارة الإصدارات هذه الإصدار الدلالي (⁨Semantic Versioning⁩) 2.0.0. ويتّبع توليد سجل التغييرات ⁨Conventional Commits 1.0.0.⁩

السياق التجاري

يتّبع ⁨NextPDF Pro⁩ و⁨NextPDF Enterprise⁩ قواعد استقرار واجهة مزوّد الخدمة نفسها التي يتّبعها ⁨Core.⁩ يظل العقد الذي تستهدفه في ⁨Core⁩ صالحًا أمام تطبيق ⁨Premium⁩ لذلك العقد، وبذلك تبقى شيفرة التوسعة الخاصة بك قابلة للنقل عبر الإصدارات.

انظر أيضًا

• نظرة عامة على تأليف التوسعات
• الخطوط المخصّصة
• مشغّلات الإجراءات ومستمعو الأحداث
• عقد مزوّد ⁨KMS⁩

العقود والوحدات ذات الصلة

• مرجع وحدة العقود — خريطة العقود المُولَّدة ونص الوعد الخاص بكل عقد.
• مرجع عقود التدفق — عقود التدفق experimental وتطبيقاتها المشحونة.
• مرجع عقود التوقيع — عقود التوقيع stable وexperimental وفق القواعد نفسها.
• نظرة عامة على تأليف التوسعات — ماذا يعني كل وسم @stability عمليًا.
• مشغّلات الإجراءات ومستمعو الأحداث — المُوزِّع final والحمولات التجريبية التي تحكمها هذه القواعد.

يعرّف المسرد وسم الاستقرار ووعد التوافق مع الإصدارات السابقة. راجع المسرد المنشور للاطلاع على التعريفات المعتمدة.