كتاب وصفات التكامل

كتاب وصفات التكامل

تُصيّر نواة ⁨NextPDF⁩ تنسيق المستندات المنقولة (⁨PDF⁩) 2.0 من ⁨PHP.⁩ تربط حزم التكامل التسع هذا المحرك بإطار عمل، أو خلفية تصيير، أو قاعدة شِفرة قديمة، أو خط أنابيب بناء، أو خدمة شبكية. تشرح هذه الصفحة الغرض من كل تكامل، وتسرد اسم حزمته وقيد إصدار النواة الخاص به (كما يُقرأ مباشرةً من composer.json الخاص به)، وتوفّر روابط إلى وصفات كل تكامل عندما تشحن مستودعاتها المصدرية أشجار docs/public/ الخاصة بها.

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

أشكال التكامل الخمسة

تندرج الحزم التسع ضمن خمسة أشكال. يوضح لك كل شكل نوع المشكلة التي يحلها التكامل.

• تكاملات أُطُر العمل تربط ⁨NextPDF⁩ بحاوية خدمات إطار عمل التطبيق ودورة حياة الطلب الخاصة به: nextpdf/laravel، وnextpdf/symfony، وnextpdf/codeigniter. ثبّت أحدها، واستخرج الخدمة، وأعد استجابة ⁨PDF.⁩
• جسور المُصيِّرات ترسل خطوة التحويل من ⁨HTML⁩ إلى ⁨PDF⁩ أو من ⁨Office⁩ إلى ⁨PDF⁩ إلى خلفية تصيير خارجية بدلًا من خط الأنابيب داخل العملية: nextpdf/artisan (متصفح ⁨Chrome⁩ بلا واجهة عبر بروتوكول ⁨Chrome DevTools⁩)، وnextpdf/gotenberg (خدمة ⁨Gotenberg⁩ المصغّرة)، وnextpdf/cloudflare (تصيير المتصفح من ⁨Cloudflare⁩ عند الحافة).
• طبقة توافق تتيح لقاعدة شِفرة مكتوبة لمكتبة ⁨PDF⁩ قديمة استدعاء ⁨NextPDF⁩ قبل إعادة كتابتها: nextpdf/compat-legacy.
• أداة بناء تنتج نسخة متوافقة مع الإصدارات الأقدم ⁨PHP 8.1⁩ / 7.4 من ⁨NextPDF⁩ لأوقات التشغيل التي لا يمكنها تشغيل 8.4: nextpdf/backport-builder.
• خدمة شبكية تكشف ⁨NextPDF⁩ عبر نقل الحالة التمثيلي (⁨REST⁩)، و⁨gRPC⁩، وبروتوكول ⁨Model Context⁩ لأنظمة الذكاء الاصطناعي والمستدعين البعيدين: nextpdf/server (يُوزَّع باسم ⁨NextPDF Connect⁩).

تعتمد جسور المُصيِّرات التي تتخاطب عبر بروتوكول نقل النص التشعبي (⁨HTTP⁩) (nextpdf/gotenberg، وnextpdf/cloudflare، ومسار عميل ⁨HTTP⁩ في nextpdf/laravel) على عميل ⁨HTTP⁩ وفق توصية معيار ⁨PHP⁩ رقم 18 (⁨PSR-18⁩) يوفّره التطبيق المضيف. بموجب ⁨PSR-18⁩ §4، لا يرمي العميل استثناء عميل محدد النوع إلا عندما يتعذّر عليه إرسال الطلب من الأساس. استجابة ⁨HTTP⁩ من نوع 4xx أو 5xx هي قيمة إرجاع عادية، وليست استثناءً، بموجب البند نفسه ⁨PSR-18⁩ §4. تعالج الوصفات التي تستدعي مُصيِّرًا بعيدًا أخطاء النقل ورموز الحالة غير الناجحة كحالات منفصلة.

مرجع الحزمة وقيد النواة

كل قيمة أدناه تأتي من composer.json الخاص بالحزمة المسمّاة (المصدر الموثوق). قيد النواة هو متطلب nextpdf/core المعلَن للحزمة. لا تعلن nextpdf/backport-builder أي متطلب nextpdf/core لأنها تحوّل مصدر المحرك بدلًا من الاعتماد عليه أثناء التشغيل.

التكامل	الحزمة	الشكل	قيد النواة	الوصفة
⁨Laravel⁩	nextpdf/laravel	إطار عمل	^3.0 || ^5.2	بدء سريع مع ⁨Laravel⁩ [[/⁨integrations/laravel/quickstart/⁩]]
⁨Symfony⁩	nextpdf/symfony	إطار عمل	^3.0 || ^5.2	بدء سريع مع ⁨Symfony⁩ [[/⁨integrations/symfony/quickstart/⁩]]
⁨CodeIgniter 4⁩	nextpdf/codeigniter	إطار عمل	^3.0 || ^5.2	بدء سريع مع ⁨CodeIgniter⁩ [[/⁨integrations/codeigniter/quickstart/⁩]]
⁨Artisan⁩ (⁨Chrome⁩)	nextpdf/artisan	جسر مُصيِّر	^3.0 || ^5.2	بدء سريع مع ⁨Artisan⁩ [[/⁨integrations/artisan/quickstart/⁩]]
⁨Gotenberg⁩	nextpdf/gotenberg	جسر مُصيِّر	^3.0	بدء سريع مع ⁨Gotenberg⁩ [[/⁨integrations/gotenberg/quickstart/⁩]]
⁨Cloudflare⁩	nextpdf/cloudflare	جسر مُصيِّر	^3.0	بدء سريع مع ⁨Cloudflare⁩ [[/⁨integrations/cloudflare/quickstart/⁩]]
التوافق (القديم)	nextpdf/compat-legacy	طبقة توافق	^3.0	بدء سريع مع ⁨Compat-legacy⁩ [[/⁨integrations/compat-legacy/quickstart/⁩]]
أداة ⁨Backport builder⁩	nextpdf/backport-builder	أداة بناء	غير منطبق	بدء سريع مع ⁨Backport⁩ [[/⁨integrations/backport/quickstart/⁩]]
⁨Connect⁩ (الخادم)	nextpdf/server	خدمة شبكية	^3.0	بدء سريع مع ⁨Connect⁩ [[/⁨integrations/connect/quickstart/⁩]]

يوزّع ⁨NextPDF⁩ الحزمة nextpdf/server تحت اسم المنتج ⁨NextPDF Connect⁩؛ وتقع وصفاتها تحت اللاحقة connect. وتُشحن nextpdf/compat-legacy من عائلة compat؛ وتقع وصفاتها تحت اللاحقة compat-legacy.

تتطلب كل حزمة ⁨PHP⁩ >=8.4 <9.0 في وقت تشغيلها الخاص. توجد nextpdf/backport-builder لإنتاج عناصر تعمل على ⁨PHP 8.1⁩ (وهدف 7.4). المحرك المنقول الناتج، لا الأداة، هو ما يعمل على وقت التشغيل الأقدم.

الغرض من كل تكامل

تكاملات أُطُر العمل

• nextpdf/laravel — مزوّد خدمة ⁨Laravel 12⁩، وواجهة (⁨facade⁩)، ومساعدات استجابة ⁨PDF.⁩ استخدمه عندما يكون تطبيقك تطبيق ⁨Laravel⁩ وتريد الحصول على ⁨NextPDF⁩ من الحاوية وإعادته كاستجابة ⁨HTTP⁩ دون توصيل يدوي. الوصفة: [[/⁨integrations/laravel/quickstart/⁩]].
• nextpdf/symfony — حزمة ⁨Symfony 7⁩ مع خدمات حقن التبعيات ومساعدات استجابة ⁨PDF.⁩ استخدمه عندما يكون تطبيقك تطبيق ⁨Symfony.⁩ تسجّل الحزمة المحرك كخدمة وتتكامل مع استجابات symfony/http-foundation. الوصفة: [[/⁨integrations/symfony/quickstart/⁩]].
• nextpdf/codeigniter — خدمة ⁨CodeIgniter 4⁩، وغلاف مكتبة، ومساعدات استجابة ⁨PDF.⁩ استخدمه عندما يكون تطبيقك تطبيق ⁨CodeIgniter 4⁩ وتريد إتاحة ⁨NextPDF⁩ عبر محدِّد خدمات إطار العمل. الوصفة: [[/⁨integrations/codeigniter/quickstart/⁩]].

جسور المُصيِّرات

• nextpdf/artisan — مُصيِّر ⁨Chrome⁩ بلا واجهة عبر بروتوكول ⁨Chrome DevTools.⁩ استخدمه عندما يحتاج مستند إلى محرك ⁨CSS⁩ الخاص بمتصفح من أجل دقة تخطيط لا يستهدفها خط أنابيب ⁨HTML⁩ داخل العملية، ويمكنك تشغيل عملية ⁨Chrome⁩ بالقرب من التطبيق. الوصفة: [[/⁨integrations/artisan/quickstart/⁩]].
• nextpdf/gotenberg — تحويل من ⁨Office⁩ إلى ⁨PDF⁩ ومن ⁨HTML⁩ إلى ⁨PDF⁩ عبر خدمة ⁨Gotenberg⁩ المصغّرة. استخدمه عندما يكون الإدخال مستند ⁨Office⁩، أو عندما يجب أن يعمل التصيير خارج العملية في خدمة منفصلة. يتخاطب عبر ⁨HTTP⁩ باستخدام عميل ⁨PSR-18⁩ يوفّره المضيف. الوصفة: [[/⁨integrations/gotenberg/quickstart/⁩]].
• nextpdf/cloudflare — تصيير بلا خادم عبر واجهة برمجة تطبيقات ⁨Cloudflare Browser Rendering.⁩ استخدمه عندما ينبغي أن يعمل التصيير عند الحافة من دون الحاجة إلى تشغيل عملية متصفح طويلة الأمد. يتخاطب عبر ⁨HTTP⁩ باستخدام عميل ⁨PSR-18⁩ يوفّره المضيف. الوصفة: [[/⁨integrations/cloudflare/quickstart/⁩]].

طبقة توافق

• nextpdf/compat-legacy — طبقة توافق لقواعد الشِّفرة المكتوبة لمكتبة ⁨PDF⁩ قديمة. استخدمها لاستدعاء ⁨NextPDF⁩ من الشِّفرة الموجودة قبل إعادة كتابة مواضع الاستدعاء. هي مساعد ترحيل، لا تبعية دائمة. الوصفة: [[/⁨integrations/compat-legacy/quickstart/⁩]].

أداة بناء

• nextpdf/backport-builder — خط أنابيب خفض إصدار قائم على ⁨Rector⁩ ينتج نسخة ⁨PHP 8.1⁩ (وهدف 7.4) من ⁨NextPDF.⁩ استخدمه عندما لا يستطيع وقت التشغيل الانتقال إلى ⁨PHP 8.4⁩ ولا تزال بحاجة إلى المحرك هناك. هي بنية تحتية للبناء، لا تبعية وقت تشغيل لتطبيق. الوصفة: [[/⁨integrations/backport/quickstart/⁩]].

خدمة شبكية

• nextpdf/server (⁨NextPDF Connect⁩) — يكشف ⁨NextPDF⁩ عبر واجهة برمجة تطبيقات ⁨REST⁩، وخدمة ⁨gRPC⁩، وبروتوكول ⁨Model Context.⁩ استخدمه عندما يكون المستدعون بعيدين، أو يستخدمون لغة أخرى، أو يكونون أنظمة ذكاء اصطناعي تحتاج إلى نقطة نهاية أداة بدلًا من مكتبة ⁨PHP.⁩ الوصفة: [[/⁨integrations/connect/quickstart/⁩]].

كيف تُحلّ روابط الوصفات

كل عنصر نائب [[…]] أعلاه هو مرجع أمامي لصفحة مؤلَّفة في مستودع التكامل تحت docs/public/ ويسحبها المُجمِّع إلى هذا الموقع. تتبع لواحق الأهداف اصطلاحًا واحدًا:

/integrations/<integration>/<recipe>/

الرمز <integration> هو الاسم القصير المأخوذ مباشرةً من جدول مرجع الحزمة وقيد النواة أعلاه. يوفّر كل صف في ذلك الجدول اسمًا قصيرًا واحدًا. أول وصفة يشحنها كل تكامل تُسمّى quickstart؛ وتستخدم الوصفات اللاحقة مقاطع <recipe> إضافية تحت الجذر نفسه <integration>. إلى أن تُجمَّع صفحة هدف، يكون رابطها عنصرًا نائبًا ولا يُحَلّ. هذا الفهرس لا يقدّم أي ادعاء سلوكي بشأن أي صفحة هدف. يسجّل فقط حقائق الحزمة المتحقَّق منها من composer.json واللاحقة التي ستشغلها وصفات كل مستودع.

انظر أيضًا

• اختيار تكامل — مصفوفة قرار تربط حالات الاستخدام بالتكاملات.
• اصطلاحات الوصفات — العقد الذي تتبعه كل وصفة قابلة للتشغيل في كتاب الوصفات هذا.