فلسفة تصميم NextPDF

Spec: ISO/IEC 25010 Spec: ISO 32000-2 Evidence: Design principle

لمحة سريعة

تعرض هذه الصفحة المبادئ التي تُحتكم إليها كل قرارات واجهة ⁨NextPDF⁩ البرمجية. وهي قليلة عن قصد، لأن المبدأ الذي لا تستطيع استحضاره لا تستطيع تطبيقه تحت الضغط.

هذه هي الصفحة التي ينبغي قراءتها أولاً. أما صفحات ⁨Insider_⁩ الأخرى فتُظهر هذه المبادئ وهي تعمل في مواضع محددة. وهذه الصفحة تُسمّيها كي يكون لبقية الصفحات معنى.

لماذا يهم هذا

إن صيغة ⁨PDF⁩ راسخة بما يكفي لتكون لها مواقفها، وصارمة بما يكفي لتعاقب على التخمينات. فالتوقيع يغطي بالضبط البايتات التي يغطيها، لا أكثر. والخط إما أن يكون مضمَّناً أو لا يكون. وملف الأرشفة إما أن يصمد أو يسقط في تدقيق يجري بعد أشهر، أمام شخص يحتاج إلى دليل.

أمام المكتبة خيار حين تكون المدخلات غامضة: إما أن تخمّن وتلزم الصمت، أو أن تتوقف وتُصرّح بذلك. يبدو الخيار الأول أكثر وُدّاً في عرض توضيحي. لكنه قد يكلّفك أيضاً حادثاً في بيئة الإنتاج لا يترك أثراً يوضح ما الخطأ الذي حدث. ويختار NextPDF الخيار الثاني. فهو يقبل انطباعاً أول أقل طمأنينة مقابل موقف قابل للدفاع عنه. وتسمّي معايير جودة البرمجيات هذه المقايضة مباشرة. سلوك الأمان عند الفشل (Fail-safe) هو قدرة المنتج على العودة إلى حالة آمنة عند الفشل بدلاً من الاستمرار في حالة غير معرَّفة ( Spec: ISO/IEC 25010, §3 ).

النسخة الموجزة

يقوم ⁨NextPDF⁩ على خمسة مبادئ، مرتَّبة حسب الأولوية:

الصريح يتفوق على الضمني. إذا كان للقصد أهمية، فعليك التصريح به. لا يستنتج المحرك مستوى توقيع، أو وضع إخراج، أو هدف مطابقة من السياق.
افشل بسرعة، افشل بوضوح، افشل مبكراً. يُرفَض المدخل غير الصالح قبل كتابة أي بايت، برسالة تذكر السبب صراحة.
الأخطاء جزء من سطح الواجهة البرمجية. الإخفاقات محددة ومُصنَّفة بأنواع وتحمل سياقاً مُهيكلاً — مُصمَّمة لا عرضية.
الحدود مُعلَنة لا مُكتشَفة. كل ادعاء يقول أين يتوقف. “ضروري لا كافٍ” عبارة يذكرها ⁨NextPDF⁩ عن قصد.
لا شيء يتدهور بصمت. لا يُعيد المحرك مُخرَجاً نصف صحيح يبدو مكتملاً.

وكل ما عدا ذلك — الباني الانسيابي، والمستند القابل للتخلص منه، والتصنيف الصارم بالأنواع — يتفرّع عنها.

كيف يتعامل ⁨NextPDF⁩ مع ذلك

المبادئ ليست شعارات. فهي تظهر بأشكال ملموسة في الشيفرة المصدرية، ويعزّز بعضها بعضاً.

يربط الجدول أدناه كل مبدأ بالموضع الذي يمكنك أن تراه فيه داخل المحرك وبما يكلّفه غيابه.

المبدأ	كيف يظهر في ⁨NextPDF⁩	تكلفة النقيض
الصريح يتفوق على الضمني	تأخذ `setSignature(certInfo:, level:)` مستوى ⁨PAdES⁩ بوصفه وسيطاً مطلوباً ومُسمّى — فلا وجود لمستوى “تلقائي”	مستند موقَّع بملف لم يكن الالتزام يتطلبه، يُكتشَف ذلك عند وقت التحقق
افشل بسرعة، افشل بوضوح	ترفض `save()` مساراً يستخدم مُغلِّف دفق أو يحوي بايت صفري قبل التصيير؛ واستدعاء `setSignature()` متبوعاً بـ `save()` يرمي استثناءً بدلاً من إصدار ملف غير موقَّع	كتابة عبر اجتياز المسار، أو ملف ⁨PDF⁩ “غير موقَّع ويُظَن أنه موقَّع” داخل أرشيف
الأخطاء جزء من سطح الواجهة البرمجية	استثناء أساس مجرد واحد، وأصناف فرعية محددة ومُصنَّفة بأنواع، يكشف كل منها `getContext()` مُهيكلاً لأجل السجلات ومراقبة أداء التطبيقات ⁨APM⁩	تتبُّع مكدّس عام وظهيرة طويلة من التخمين
الحدود مُعلَنة	تُعيد فحوص المطابقة داخل العملية نتائج وتذكر صراحةً أن الحكم يعود إلى مُدقِّق مستقل	استنتاج “لا استثناء، إذاً لا بد أنه مطابق” يدحضه مُدقِّق
لا شيء يتدهور بصمت	يرفض مسار الطابع الزمني الأرشيفي إعادة ملف مكتوب جزئياً بدلاً من إصدار ملف ينقصه قاموسه المطلوب	ملف تحقق طويل الأمد ليس كذلك في الحقيقة دون إعلان

اقرأ المبادئ مجتمعة فيبرز لك موقف واحد: المحرك يفضّل أن يمنحك “لا” صادقة على “ربما” واثقة. وليس ذلك تشاؤماً. بل هو إدراك أن ملف ⁨PDF⁩ كثيراً ما يكون مُستنَداً قانونياً. والمستند القانوني الخاطئ أسوأ من مستند لم يُنتَج أصلاً.

ثمة سبب يتعلق بالعوامل البشرية وراء إعلان الحد قبل أن تتبنّى الأداة، لا بعد ذلك. ينبغي أن يكون القارئ قادراً على إدراك ما إذا كان المنتج يلائم حاجته من الانطباعات الأولى ومن توثيقه، لا فقط بعد الالتزام به ( Spec: ISO/IEC 25010, §3.26 ). ولهذا تبدأ كل صفحة ⁨Insider_⁩ — بما فيها هذه — بتعريف ما هي عليه وتنتهي عند الحد الذي تتوقف عنده، ولهذا توجد صفحة كاملة عن متى لا تستخدم ⁨NextPDF⁩. إن إخبارك بالحد مبكراً هو لطف، لا ضعف.

ما الذي يقوله الدليل

هذه الصفحة بيان من نوع Evidence: Design principle : فالمبادئ قرارات مقصودة، يُحتجّ لها ولا تُقاس. وحيثما كان للمبدأ اسم في تخصص خارجي، تستند الصفحة إليه كي لا يكون التعليل مجرد رأي داخلي.

إن موقف “الرفض بدلاً من الاستمرار في حالة غير معرَّفة” هو خاصية الجودة الأمان عند الفشل (fail-safe) في Spec: ISO/IEC 25010 §3 — أي أن المنتج يضع نفسه في حالة آمنة عند الفشل. والتحمّل للأعطال (fault tolerance)، ضمن العائلة نفسها، هو الدرجة التي يظل بها النظام يتصرف كما هو مقصود رغم الأعطال. ويوجّه NextPDF ذلك الجهد نحو الكشف والتوقف، لا نحو إخفاء العطل.
إن موقف “إعلان الحد قبل التبنّي” هو قابلية التعرّف على الملاءمة (appropriateness recognizability) ( Spec: ISO/IEC 25010, §3.26 ): أي القدرة على الحكم على الملاءمة من التوثيق والانطباعات الأولى.
والسبب الخاص بـ PDF في أهمية أي من هذا هو Spec: ISO 32000-2, §12.8 : فنطاق بايتات التوقيع يحمي بالضبط البايتات التي يغطيها لا أكثر، ومن ثَم فإن محركاً “يتطوّع” بإعادة كتابة مستند موقَّع أو التخمين حوله لم يقدّم أي مساعدة على الإطلاق.

تُبيَّن المبادئ كلٌّ على حدة مقابل شيفرة المحرك الحقيقية في صفحاتها الخاصة — وتحمل صفحتا واجهة برمجية ترفض التخمين والأخطاء كميزة Evidence: Code-backed البرهان. هذه الصفحة هي “لماذا”؛ وتلك الصفحات هي “ماذا”.

مثال عملي

تظهر المبادئ في بضعة أسطر من الاستخدام العادي. يُصرّح استدعاء التوقيع بالقصد صراحةً. ويرفض المحرك مبكراً بدلاً من إصدار شيء مُضلِّل.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Exception\NotImplementedException;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;

$document = Document::createStandalone();
$document->setTitle('Service Agreement 2026-0042');
$document->addPage();
$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This agreement is configured for a PAdES signature.', newLine: true);

// Explicit beats implicit: the PAdES level is a required, named argument.
// There is no inferred or "auto" level.
$document->setSignature(
    certInfo: new CertificateInfo(
        certificate: $certificatePem,
        privateKey: $privateKeyPem,
    ),
    level: SignatureLevel::PAdES_B_B,
);

try {
    // Fail fast, no silent degradation: rather than emit an UNSIGNED file
    // that the caller believes setSignature() signed, the high-level path
    // refuses and names the supported route.
    $document->save('/srv/output/agreement.pdf');
} catch (NotImplementedException $e) {
    // The message identifies the feature and the follow-up, not a stack
    // trace: "... is not implemented in this release. <actionable follow-up>"
    error_log($e->getMessage());
}

ليست النقطة في آليات التوقيع. ففي مقتطف واحد تظهر ثلاثة مبادئ: القصد مُصرَّح به (level:)، والفشل مبكر ومُسمّى، والمحرك يأبى أن يُنتج مستنداً يكذب بشأن حالته.

مفهوم خاطئ شائع

أكثر القراءات الخاطئة شيوعاً هي أن هذه المبادئ تجعل ⁨NextPDF⁩ “أصعب في الاستخدام”. بل تجعله أصعب في الاستخدام الخاطئ. فالوسيط المطلوب يعني قيمة افتراضية صامتة أقل تفاجئك. والاستثناء المبكر يعني مُخرَجاً تالفاً أقل في الأرشيف. يُوضَع الاحتكاك عن قصد حيث يكون الخطأ زهيد التكلفة — عند موضع الاستدعاء، أثناء التطوير — بدلاً من حيث يكون باهظاً: في الإنتاج، وفي التدقيق، وفي المحكمة.

وثمة قراءة خاطئة ثانية مفادها أن “ذا مواقف محددة” يعني “غير مرن”. وهذا غير صحيح. فللمحرك مواقف بشأن الصحة والقصد، لا بشأن مستندك. ولا تزال تتحكم تحكماً كاملاً في التخطيط والمحتوى والخطوط والبنية. إن المواقف تتعلق بعدم التخمين نيابةً عنك حيث يكون التخمين غير آمن.

الحدود والقيود

تعرض هذه الصفحة قصد التصميم. وهي ليست بحد ذاتها مواصفة سلوكية. تصف المبادئ كيفية اتخاذ القرارات، لا ضماناً بشأن أي طريقة بعينها. أما العقد الدقيق لكل طريقة فيوجد في المرجع وفي صفحة ⁨Insider_⁩ الخاصة بها، وفق مستوى الدليل الخاص بتلك الصفحة.

كما أن المبادئ ليست قوانين فيزيائية مطلقة. بل هي أولويات تُطبَّق بحُسن تقدير. وحيثما تعارض مبدآن (رفض أكثر صرامة في مقابل قيمة افتراضية أكثر تسامحاً)، يكون ترتيب الأولوية أعلاه هو الفيصل. وقد توثّق وحدة بعينها استثناءً مُعلَّلاً. وحين تفعل ذلك، يُدوَّن ذلك الاستثناء، لا يُفترَض.

وأخيراً، فإن “مبدأ التصميم” هو أساس الدليل هنا عن قصد. هذه الصفحة تحتجّ. وهي لا تقيس الأداء. أما الادعاءات التي تحتاج إلى رقم أو اختبار أو بند لتُسنَد، فتُطرح في الصفحات التي تملك ذلك الدليل، لا هنا.

مستندات ذات صلة

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

مسرد المصطلحات

مبدأ التصميم (مستوى الدليل) — صفحة تكون ادعاءاتها قرارات تصميم مقصودة، يُحتجّ لها انطلاقاً من القصد والمعايير المؤيِّدة بدلاً من قياسها باختبار مرجعي أو اختبار واحد.
الأمان عند الفشل (⁨Fail-safe⁩) — خاصية من خصائص جودة البرمجيات: عند الفشل، يعود المنتج إلى حالة آمنة بدلاً من الاستمرار في حالة غير معرَّفة. وهو السبب في أن ⁨NextPDF⁩ يرفض بدلاً من أن يخمّن.
الفشل السريع (⁨Fail fast⁩) — رفض المدخل غير الصالح عند أبكر نقطة ممكنة، بسبب واضح، بدلاً من المضي قدماً والفشل بغموض لاحقاً.
⁨PAdES⁩ — التوقيعات الإلكترونية المتقدمة لـ ⁨PDF⁩، عائلة ملفات تعريف ⁨ETSI⁩ لتوقيع مستندات ⁨PDF⁩ (⁨B-B⁩، ⁨B-T⁩، ⁨B-LT⁩، ⁨B-LTA⁩). مشروح هنا عند أول استخدام؛ ومُتناوَل بتعمّق في صفحات التوقيع.
ضروري لا كافٍ — صياغة مقصودة تُستخدم حين يكون فحص داخل العملية إشارة حقيقية لكنه ليس حكم مطابقة؛ فالقرار الموثوق يعود إلى مُدقِّق مستقل.