اصطلاحات الوصفات

اصطلاحات الوصفات

تلتزم كل وصفة قابلة للتشغيل في كتاب وصفات التكامل بالعقد نفسه. توثّق هذه الصفحة ذلك العقد لتعرف ما تتوقعه من الوصفة وما يجب على مؤلفها توفيره. هذه صفحة وصفية: تسجّل الاصطلاح فقط. أما فرض هذه الاصطلاحات فيتم في أدوات المستودع وفي ورقة تجاوزات النمط، لا هنا.

يخزّن كل تكامل وصفاته في docs/public/ داخل مستودع المصدر الخاص به، ثم يسحبها المُجمِّع إلى هذا الموقع. تنطبق هذه الاصطلاحات حيثما وُجدت الوصفة.

1. العيّنات شيفرة حقيقية، لا مقتطفات مكتوبة يدويًا

توجد شيفرة الوصفة في مستودع، وليست مقتطفًا مكتوبًا داخل النص.

• تأتي كل كتلة شيفرة ⁨PHP⁩ يتجاوز طولها خمسة أسطر من دليل examples/ في المستودع المقابل، أو من دليل tests/Cookbook/.
• تصرّح الكتلة بمصدرها في سلسلة معلومات الكتلة المُسيَّجة، مثل title="examples/standalone.php".
• يؤكّد اختبار مقابل أن المثال لا يزال يُترجَم وينتج المُخرَج الموثَّق، بحيث لا يمكن للصفحة المعروضة أن تنحرف عن الشيفرة التي تعرضها.

ينبثق هذا الاصطلاح من ورقة تجاوزات نمط التوثيق §3.4 (“يجب أن تكون العيّنات قابلة للتشغيل”). ولا تستوفي الاصطلاح أي وصفة تعرض شيفرة دون مثال أو اختبار داعم.

2. لغة واحدة لكل كتلة، مع إظهار معالجة الأخطاء

• تحتوي كل كتلة شيفرة مُسيَّجة على لغة واحدة بالضبط، معلَنة صراحةً ( ```php، ```bash، ```yaml، ```json). لا تُستخدَم الأسيجة المجردة.
• تُظهِر الوصفة الموسومة بأنها دليل جاهز للإنتاج try / catch صراحةً، وتلتقط أكثر أنواع الاستثناءات المنطبقة تحديدًا بدلًا من \Exception المجرّد، وتجعل كتلة الالتقاط تؤدي إجراءً يمكن للقارئ نسخه (تسجيل، أو إعادة الرمي، أو إرجاع كائن خطأ معرَّف). لا تُستخدَم كتل الالتقاط الفارغة.
• في تكاملات النقل عبر بروتوكول نقل النص التشعبي (⁨HTTP⁩)، تتعامل الوصفة مع فشل النقل وحالة ⁨HTTP⁩ غير الناجحة بوصفهما حالتين منفصلتين. لا يرفع عميل توصية معايير ⁨PHP⁩‏ (⁨PSR⁩)-18 استثناء عميل مُصنَّف النوع إلا عندما يتعذّر إرسال الطلب. وتكون الاستجابة 4xx أو 5xx قيمة إرجاع عادية تفحصها الوصفة، لا استثناءً تلتقطه.

3. البيانات التمهيدية لقابلية التكرار

تعلن كل وصفة مدى قابلية مُخرَجها للتكرار، وتستخدم عقد البيانات التمهيدية §5.1 الذي يفرضه مخطط محتوى الموقع. الحقول ذات الصلة هي:

• reproducibility_profile — واحد من bitwise، أو structural، أو semantic. يعني bitwise أن بايتات المُخرَج متطابقة عبر التشغيلات عند تثبيت المدخلات. ويعني structural أن بنية المستند متطابقة، مع احتمال اختلاف البايتات العَرَضية (الطوابع الزمنية، وترتيب الكائنات). ويعني semantic أن النتيجة المعروضة مكافئة، دون ضمان على مستوى البايت أو البنية. تذكر الوصفة أقوى ملف يمكنها دعمه بصدق، لا أقوى ملف متاح.
• output_hash — عندما يكون الملف bitwise، تكون القيمة تجزئة ⁨SHA-256⁩ للمُخرَج المتوقَّع، بحيث يستطيع القارئ التحقق من النتيجة الموثَّقة. ويُترك الحقل فارغًا عندما لا يدعم الملف تجزئة مستقرة.
• runnable_example — مسار examples/… الذي ينتج مُخرَج الوصفة، ويربط الصفحة بالعيّنة المدعومة بمصدرها في §1.
• performance_budget — حد اختياري لزمن الساعة الفعلي وذروة الذاكرة للوصفة، بحيث تظل الوصفة التي تطرح أيضًا ادعاءً بشأن الأداء محدودة النطاق وقابلة للاختبار.
• compatibility — إصدارات ⁨PHP⁩ التي تدّعي الوصفة أنها تعمل عليها. تعتمد الوصفات ⁨PHP⁩ 8.4 افتراضيًا؛ والوصفة التي تذكر ميزة خاصة بالإصدار 8.4 فقط تدرج النقل العكسي في بياناتها التمهيدية وتشير إلى الميزة في كتلة الشيفرة.

يمثّل ملف قابلية التكرار عقد قابلية التكرار §8.4. استخدمه لتحديد ما إذا كان “المُخرَج” يعني بايتات دقيقة أم مستندًا مكافئًا.

4. بوابة النشر

تحمل كل صفحة في كتاب الوصفات هذا publish: false إلى أن تجتاز بوابة الكتابة. الافتراض هو الرفض: دمج الصفحة لا ينشرها؛ ولا ينشرها إلا قرار بوابة صريح مسجَّل في البيانات التمهيدية. الوصفة التي يتعذّر تثبيت استشهاداتها المعيارية بسبب انقطاع فعلي في محرك الامتثال تحمل أيضًا علامة استشهاد غير محسومة. وتظل publish: false إلى أن يُعاد تثبيت الاستشهاد. يحكم تلك العلامةَ بروتوكولُ الاحتياط عند انقطاع البنية التحتية للتوليد المعزَّز بالاسترجاع (⁨RAG⁩) في المستودع؛ ويتبع مؤلف الوصفة ذلك البروتوكول بدلًا من اختلاق استشهاد أو إسقاط الادعاء.

5. يكتب المُجمِّع حقول المصدر

لا يكتب مؤلف الوصفة يدويًا حقول مصدر المنشأ الأربعة التي يملكها المُجمِّع: source_repo، وsource_ref، وsource_hash، وmanifest_hash. يملؤها المُجمِّع عند سحب الوصفة من مستودع مصدرها، بحيث تسجّل الصفحة المنشورة بدقة مراجعة المستودع التي أنتجتها. إذا ترك المؤلف عنصرًا نائبًا في أي من هذه الحقول، استبدله المُجمِّع؛ ولا يصل العنصر النائب إلى الصفحة المنشورة أبدًا.

الملخّص

تتضمن الوصفة في كتاب الوصفات هذا شيفرة مدعومة بمصدرها ومرفقة باختبار، ولغة واحدة لكل كتلة، ومعالجة أخطاء صريحة لأدلة الإنتاج، وملف قابلية تكرار صادق، وافتراض publish: false حتى بوابة الكتابة، ومصدر منشأ يحقنه المُجمِّع. الصفحة التي تستوفي هذه العناصر الستة جميعها وصفة؛ والصفحة التي تستوفي أقل من ذلك مسوَّدة.

انظر أيضًا

• كتاب وصفات التكامل — مرجع الحزمة وقيود النواة.
• اختيار تكامل — مصفوفة القرار لحالات الاستخدام.