دليل اتخاذ قرار التكامل

Spec: ISO/IEC/IEEE 26514:2022, §3.x162 Spec: ISO 24495-1:2023, §5 Evidence: Editorial

لمحة سريعة

تتكوّن منظومة ⁨NextPDF⁩ من محرّك أساسي صغير ومجموعة حِزم لكل منها غرض محدّد: جسور أُطر العمل، ومحرّكا عرض ⁨HTML⁩، ومحرّك عرض على الحافة، وخادم تنفيذ. تربط هذه الصفحة حالات الاستخدام الواقعية بالحزمة المناسبة، استنادًا إلى ما تحتويه كل حزمة فعليًا. يبقى الاختيار بيدك، مستندًا إلى الأدلة بدلًا من أن يكون مضمَّنًا في التوثيق.

لماذا يهمّ هذا

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

باختصار

ابدأ بالمحرّك الأساسي. كل ما عداه إضافي. إذا عرض المحرّك داخل العملية مستندك بشكل صحيح، فلن تحتاج إلى أي حزمة عرض على الإطلاق.
جسر إطار العمل يتبع إطار عملك، لا مستندك. توجد تكاملات ⁨Laravel⁩ و ⁨Symfony⁩ و ⁨CodeIgniter⁩ لتمنحك واجهة (⁨facade⁩) أو مصنعًا (⁨factory⁩)، واستجابة ⁨PDF⁩، وتوليدًا مُدرَجًا في طابور، واكتشافًا تلقائيًا — لكنها لا تُغيِّر ما يستطيع المحرّك عرضه.
استخدم محرّك عرض فقط عندما تتطلّب دقّة ⁨CSS⁩ متصفِّحًا. توجد ⁨Artisan⁩ (‏⁨Chrome⁩ محلي) و ⁨Cloudflare⁩ (متصفِّح على الحافة) لهذا الغرض تحديدًا؛ وتوجد ⁨Gotenberg⁩ لإدخال مستندات ⁨Office.⁩
استخدم ⁨Connect⁩ عندما يكون المُستدعي خدمةً أو وكيل ذكاء اصطناعي، لا استدعاء ⁨PHP.⁩ يكشف المحرّك عبر ⁨MCP⁩ و ⁨REST⁩ و ⁨gRPC⁩ مع بوابة موافقة بشرية للعمليات الخطِرة.

كيف يتعامل ⁨NextPDF⁩ مع الأمر

صُمِّمت المنظومة على طبقات بحيث تكون لكل حزمة مهمة واحدة. يعرض المحرّك الأساسي ⁨PDF⁩ داخل العملية. ويكيّف جسر إطار العمل ذلك المحرّك مع أعراف إطار العمل. وتفوِّض حزمة العرض تخطيط ⁨HTML⁩ أو ⁨Office⁩ إلى محرّك خارجي عندما لا يكون المحرّك داخل العملية هو الأداة المناسبة. أمّا ⁨Connect⁩ فيحوِّل المحرّك إلى خدمة شبكية. لا تتداخل أي من هذه الحِزم مع مسؤولية أخرى، وهذا ما يجعل القرار قابلًا للمعالجة. أنت لا تختار بين أدوات متنافسة، بل تركِّب أدوات متكاملة.

اتّخذ القرار وفق حالة الاستخدام. يربط الجدول كل سيناريو بالحزمة المناسبة ويبيِّن المقايضة التي ستقبلها.

حالة الاستخدام	الحزمة المناسبة	ما توفّره فعليًا	المقايضة التي تقبلها
⁨PDF⁩ في تطبيق ⁨Laravel⁩	`nextpdf/laravel`	مزوّد خدمة يُكتشف تلقائيًا، وواجهة `Pdf`، و `PdfResponse` (مضمَّن/تنزيل/متدفِّق، ترويسات ⁨OWASP⁩)، ومهمة `GeneratePdfJob` مُدرَجة في طابور مع ⁨tries/timeout/backoff⁩، وسجلّات مقفلة آمنة مع ⁨Octane⁩	اعتماد على ⁨Laravel 12⁩؛ وتبقى قدرات المحرّك دون تغيير
⁨PDF⁩ في تطبيق ⁨Symfony⁩	`nextpdf/symfony`	حزمة تُسجَّل تلقائيًا، و `PdfFactory` قابل للحقن، و `PdfResponse`، ومعالج ⁨Messenger⁩ اختياري للتوليد غير المتزامن	اعتماد على حزمة ⁨Symfony 7.2⁩؛ وتبقى القدرات دون تغيير
⁨PDF⁩ في تطبيق ⁨CodeIgniter 4⁩	`nextpdf/codeigniter`	مساعد `service('pdf')` / `pdf()`، ومكتبة `Pdf` تغلِّف `Document` قابلًا للتخلّص منه، و `PdfResponse`، ومهمة اختيارية مُدرَجة في طابور	اعتماد على ⁨CodeIgniter 4.6⁩؛ وتبقى القدرات دون تغيير
المستند يحتاج إلى ⁨CSS⁩ متصفِّح كامل (⁨flex/grid/⁩خطوط ويب) بجوار العملية	`nextpdf/artisan`	⁨Chrome⁩ بلا واجهة عبر ⁨CDP⁩، يُعرض ثم يُستورد مجددًا كـ ⁨Form XObject⁩ ليبقى النص قابلًا للتحديد؛ ومجمَّع متصفِّحات	بيئة تشغيل ⁨Chrome⁩ وتكلفتها من حيث ⁨memory/process⁩ على مضيفك
مستندات ⁨Office⁩ (`.docx`، `.xlsx`) إلى ⁨PDF⁩	`nextpdf/gotenberg`	جسر ⁨PSR-18⁩ إلى خدمة ⁨Gotenberg⁩ المصغّرة بنقل مُحصَّن ضد ⁨SSRF⁩ ومثبَّت على عنوان ⁨IP⁩	خدمة ⁨Gotenberg⁩ خارجية واعتماد على الشبكة
⁨HTML⁩→⁨PDF⁩ على الحافة / دون ⁨Chrome⁩ محلي	`nextpdf/cloudflare`	عرض المتصفِّح من ⁨Cloudflare⁩ عبر نقل مثبَّت، مع احتياطي اختياري إلى ⁨Chrome⁩ محلي	حساب ⁨Cloudflare⁩ واعتماد على الشبكة؛ والاحتياطي يحتاج إلى ⁨Artisan⁩
المحرّك تستهلكه خدمة أو وكيل ذكاء اصطناعي	`nextpdf/server` (⁨Connect⁩)	محرّك واحد عبر ⁨MCP⁩ (‏⁨stdio⁩) و ⁨REST⁩ (‏⁨OpenAPI 3.1⁩) و ⁨gRPC⁩؛ واكتشاف أدوات بالاعتماد المرن؛ وبوابة تأكيد بشرية للأدوات عالية الخطورة	تشغيل سطح خدمة؛ والالتزام بالتنفيذ الحتمي

هذان قراران مستقلّان، وكثيرًا ما يخلط الناس بينهما. يُختار جسر إطار العمل بحسب إطار العمل الذي تستخدمه بالفعل — وهو لا يوسّع أو يقيّد ما يعرضه المحرّك. ويُختار محرّك العرض بحسب المستند. والسؤال الحاسم هو ما إذا كان محرّك ⁨CSS⁩ داخل العملية كافيًا، أم أن المستند يحتاج فعلًا إلى محرّك تخطيط متصفِّح. وقد تحتاج إلى جسر إطار عمل دون محرّك عرض، أو إلى محرّك عرض دون جسر، أو إلى كليهما، أو إلى لا شيء منهما. والتعامل معهما كسؤال واحد هو أكثر أخطاء التكامل شيوعًا، ولهذا تفصل بينهما هذه الصفحة.

ماذا تقول الأدلة

هذه الصفحة تحريرية — أي إنها توجيه لاتخاذ القرار — لكن هذا التوجيه مبني على ما يحتويه بيان كل حزمة وأصنافها الرئيسية.

الجسور حقيقية ومتوازية. يُعلن كل منها عن اعتماده على إطار العمل وتسجيله التلقائي في composer.json الخاص به (extra.laravel.providers، و extra.symfony.bundles، و Registrar في ⁨CodeIgniter⁩). كما يَشحن كل منها PdfResponse، وربطًا لمستند قابل للتخلّص منه، ومهمة اختيارية مُدرَجة في طابور. لا يضيف أي منها قدرة عرض — بل يكيّف المحرّك نفسه. ومحرّكات العرض حقيقية ومتمايزة. يعتمد ⁨Artisan⁩ على chrome-php/chrome ويستورد ⁨PDF⁩ الصادر من ⁨Chrome⁩ مجددًا كـ ⁨Form XObject⁩ ليبقى النص قابلًا للتحديد. و ⁨Gotenberg⁩ و ⁨Cloudflare⁩ جسرا ⁨HTTP⁩ وفق ⁨PSR-18⁩ بنُقُل مُحصَّنة صراحةً ضد ⁨SSRF⁩ ومثبَّتة على عنوان ⁨IP.⁩ ويمكن لـ ⁨Cloudflare⁩ الرجوع إلى ⁨Artisan⁩ عندما يتعذّر الوصول إلى ⁨Worker.⁩ ويُعلن composer.json الخاص بـ ⁨Connect⁩ عن النُقُل الثلاثة ونموذج اعتماد مرن تظهر فيه الأدوات عند تثبيت حِزمها، ضمن نموذج خطورة من أربعة مستويات مع بوابة تأكيد بشرية.

طريقة توجيه هذه الصفحة لك مدعومة بالمعايير من حيث الشكل: Spec: ISO 24495-1:2023, §5 يقضي بأن يكون القرّاء قادرين على التحديد السريع لما إذا كان المحتوى يخدم غرضهم، و Spec: ISO/IEC/IEEE 26514:2022, §3.x222 يتطلّب من الروابط والمراجع أن تذكر وجهتها — ولهذا يسمّي الجدول الحزمة المحدّدة والمقايضة بدلًا من الإشارة الغامضة إلى “تكامل ما”.

مثال عملي

القرار سلسلة من الأسئلة الصريحة، لا مقارنة ميزات. يحسم التدفّق التالي الحالات الشائعة.

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

الخلاصة في البنية نفسها: العرض والاستدعاء محوران منفصلان. والإجابة عنهما كسؤال واحد هي ما يقود الفِرق إلى محرّك عرض بعيد لم تكن بحاجة إليه، أو إلى جسر لا يحلّ مشكلة الدقّة لديها.

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

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

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

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

هذه الصفحة توجّه؛ وهي لا تُجري قياسًا مرجعيًا ولا ترتيبًا. بل تبيّن ما توفّره كل حزمة والمقايضة. والاختيار بينها قرارك أنت بحسب قيودك.
قدرات الحِزم تُقرأ من بياناتها وأصنافها الرئيسية في لحظة زمنية محدّدة. اعتمد توثيق كل حزمة نفسها مرجعًا موثوقًا لواجهتها البرمجية الحالية. هذا الدليل هو الخريطة، لا المواصفة.
لا تُقدَّم أي مقارنة بالمنافسين ولا يُلمَّح إليها. الموضوع الوحيد هو منظومة ⁨NextPDF⁩ وكيفية تكامل أجزائها معًا.
جسر إطار العمل ومحرّك العرض خياران مستقلّان. الجسر لا يوسّع قدرة المحرّك؛ ومحرّك العرض لا يعتمد على إطار عمل.
محرّكات العرض الخارجية تضيف اعتمادًا على التوفّر. يُدخل ⁨Gotenberg⁩ و ⁨Cloudflare⁩ استدعاءً شبكيًا وخدمة يجب تشغيلها؛ وتلك هي المقايضة المقبولة، لا تكلفة خفية.
القدرات المحجوبة بالطبقة منفصلة تمامًا عن التكامل. الميزات التجارية تُفتح بالطبقة، لا بأي جسر أو محرّك عرض؛ انظر الحدّ أدناه.

Ecosystem packages and tiering — edition availability
Edition	Availability
Core	كل حزمة تكامل (الجسور، و ⁨Artisan⁩، و ⁨Gotenberg⁩، و ⁨Cloudflare⁩، و ⁨Connect⁩) تعمل مع ⁨Core⁩ وهي مرخّصة بـ ⁨Apache-2.0.⁩ وهي تكيّف المحرّك أو تكشفه؛ ولا تحجب الميزات.
Pro	القدرات التجارية (توقيع ⁨PAdES⁩ الأساسي، و ⁨PDF/A⁩، والرموز الشريطية المتقدّمة) تُفتح بالطبقة، وتصبح حينها متاحة عبر أي تكامل، لا بتبديل التكامل.
Enterprise	الفواتير المهيكلة، وسياسات التحقّق، وبوابة التأكيد البشري للأدوات عالية الخطورة في ⁨Connect⁩ قدرات طبقة، مستقلّة عن التكامل كذلك.

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

خط أنابيب ⁨HTML⁩ — ما يغطّيه محرّك ⁨CSS⁩ داخل العملية، لتعرف متى يكون محرّك عرض المتصفِّح لازمًا فعلًا.
متى لا تستخدم ⁨NextPDF⁩ — الحدّ الصادق لمشكلات المستندات التي لا يكون المحرّك أداتها المناسبة.
أسس ⁨PHP 8.4⁩ — الحدّ الأدنى لبيئة التشغيل الذي تشترك فيه كل حزمة، وما يحافظ عليه مسار النقل الخلفي.

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

المحرّك الأساسي — nextpdf/core، محرّك ⁨PDF 2.0⁩ داخل العملية الذي تُبنى عليه كل حزمة أخرى.
جسر إطار العمل — حزمة تكامل (⁨Laravel/Symfony/CodeIgniter⁩) تكيّف المحرّك مع أعراف إطار العمل دون تغيير قدراته.
حزمة العرض — حزمة تفوّض تخطيط ⁨HTML⁩ أو ⁨Office⁩ إلى محرّك خارجي (⁨Artisan/Cloudflare/Gotenberg⁩) عندما لا يكون المحرّك داخل العملية هو الأداة المناسبة.
⁨Form XObject⁩ — جزء محتوى ⁨PDF⁩ قابل لإعادة الاستخدام؛ يستورد ⁨Artisan⁩ صفحة معروضة بالمتصفِّح كواحد منها ليبقى نصّها قابلًا للتحديد.
⁨NextPDF Connect⁩ — nextpdf/server، الحزمة التي تكشف المحرّك عبر ⁨MCP⁩ و ⁨REST⁩ و ⁨gRPC⁩ بسطح تنفيذ حتمي.
الاعتماد المرن — نموذج ⁨Connect⁩ الذي تظهر فيه الأدوات تلقائيًا مع تثبيت حِزم ⁨NextPDF⁩ الاختيارية، دون أي تغيير في الشيفرة.