تثبيت NextPDF Gotenberg

نظرة سريعة

يتألف تثبيت الجسر من جزأين: حزمة ⁨PHP⁩ وتبعيات ⁨PHP Standard Recommendation⁩ ‏(⁨PSR⁩) ⁨HTTP⁩ الخاصة بها، والتي تُثبَّت باستخدام ⁨Composer⁩، وخدمة ⁨Gotenberg⁩ التي تستدعيها الحزمة. يحوّل الجسر الملفات بإرسال العمل إلى تلك الخدمة، لذلك لا يمكنه تحويل أي شيء إلى أن تتوفر نسخة من ⁨Gotenberg⁩ يمكنه الوصول إليها.

أكمل الجزأين كليهما قبل كتابة شِفرة التحويل.

المتطلبات

المتطلب	القيد	السبب
⁨PHP⁩	>=8.4 <9.0	تُعلنه الحزمة في composer.json.
نواة ⁨NextPDF⁩	^3.0	تُعلَن كتبعية مباشرة في composer.json.
عميل ⁨PSR-18 HTTP⁩	^1.0	يرسل الجسر الطلبات عبر Psr\Http\Client\ClientInterface مُحقَن.
مصانع ⁨PSR-17 HTTP⁩	^1.1	يبني الجسر الطلبات والدفوق باستخدام مصانع ⁨PSR-17⁩ مُحقَنة.
مُسجِّل ⁨PSR-3⁩	^3.0 (اختياري)	يمكن حقن مُسجِّل لتسجيل التنقيح على مستوى الطلب.
خدمة ⁨Gotenberg⁩	قابلة للوصول عبر ⁨HTTPS⁩	تتولى الخدمة الخارجية التحويل؛ ولا تتولاه هذه الحزمة.

لا يتضمن الجسر عميل ⁨PSR-18⁩ ولا مصانع ⁨PSR-17.⁩ اختر التطبيقات التي تناسب تطبيقك. على سبيل المثال، اقرن عميلًا مبنيًّا على ⁨Guzzle⁩ مع مصانع ⁨PSR-17⁩ الخاصة به، أو استخدم عميل ⁨Symfony HTTP⁩ مع nyholm/psr7. يعمل أي تطبيق يتوافق مع عقود ⁨PSR⁩ ذات الصلة، لأن الجسر يعتمد على الواجهات لا على مكتبة بعينها.

الخطوة 1 — تثبيت الحزمة

أضف الحزمة باستخدام ⁨Composer⁩:

composer require nextpdf/gotenberg

يحلّ ⁨Composer⁩ التبعية nextpdf/core ^3.0 وعقود ⁨PSR HTTP⁩‏: psr/http-client، وpsr/http-factory، وpsr/log. لكنه لا يثبّت عميل ⁨HTTP⁩ محدَّدًا.

الخطوة 2 — تثبيت عميل ⁨PSR-18⁩ ومصانع ⁨PSR-17⁩

ثبّت عميل ⁨PSR-18⁩ واحدًا ومجموعة واحدة مطابقة من مصانع ⁨PSR-17.⁩ مع ⁨Guzzle⁩:

composer require guzzlehttp/guzzle guzzlehttp/psr7

أو مع عميل ⁨Symfony HTTP⁩ و ⁨Nyholm PSR-7⁩:

composer require symfony/http-client nyholm/psr7

مرّر هذه التطبيقات إلى مُنشئ الجسر. لا يبني الجسر عميل ⁨HTTP⁩ بنفسه أبدًا. اختر التطبيق عند توصيل الجسر. راجع /⁨integrations/gotenberg/configuration/⁩ لمعرفة شكل المُنشئ، و/⁨integrations/gotenberg/quickstart/⁩ للاطلاع على مثال توصيل كامل.

الخطوة 3 — تشغيل خدمة ⁨Gotenberg⁩

يستدعي الجسر مسار تحويل ⁨LibreOffice⁩ الخاص بـ ⁨Gotenberg⁩، لذا شغّل نسخة من ⁨Gotenberg⁩ يمكن للجسر الوصول إليها. ينشر المشروع المنبع صورة حاوية. للتطوير المحلي، استخدم:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

يُتيح هذا الأمر ⁨Gotenberg⁩ على المنفذ 3000 عبر ⁨HTTP⁩ عادي. استخدمه للتطوير المحلي فقط. يشترط الجسر ⁨HTTPS⁩ لعنوان واجهة برمجة التطبيقات ‏(⁨API⁩) المُهيّأ، ويرفض http:// العادي قبل إرسال أي طلب. لأي استخدام يتجاوز التجربة المحلية، ضع ⁨Gotenberg⁩ خلف وكيل عكسي أو شبكة خدمات تنهي أمان طبقة النقل ‏(⁨TLS⁩)، ثم وجّه الجسر إلى نقطة نهاية ⁨HTTPS.⁩ يوضح /⁨integrations/gotenberg/security-and-operations/⁩ شكل النشر في الإنتاج، والتعرّض الشبكي، والمصادقة.

وسم الصورة المعروض هنا (gotenberg/gotenberg:8) هو خط ⁨Gotenberg⁩ الرئيسي. يشير ملف ⁨README⁩ الخاص بهذا المشروع وخط أساس التكامل إلى ذلك الخط. في الإنتاج، ثبّت على وسم رقعة محدد بدلًا من تتبّع وسم رئيسي متحرك. تحقّق أيضًا من مسارات التوجيه (/forms/libreoffice/convert، و/health) مع إصدار ⁨Gotenberg⁩ الذي تنشره. يفترض الجسر هذين المسارين، ولا يضع أي افتراضات أخرى حول الخدمة.

الخطوة 4 — التحقق من التوصيل

في هذه المرحلة، تكون الحزمة وعميل ⁨HTTP⁩ قد ثُبِّتا، ويكون ⁨Gotenberg⁩ قابلًا للوصول عبر ⁨HTTPS.⁩ قبل إجراء تحويل حقيقي، تأكّد من أن الجسر يستطيع الوصول إلى الخدمة باستخدام مِسبار الصحة المدمج:

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(apiUrl: 'https://gotenberg.example.com');

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
);

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

يتحقق isAvailable() من العنوان المُهيّأ أولًا. يُرجِع false لعنوان فارغ، أو عنوان غير ⁨HTTPS⁩، أو عنوان ذي نطاق خاص دون إرسال أي حركة مرور شبكية. ثم يرسل طلب HEAD إلى <apiUrl>/health ويُبلِغ بأن الخدمة متاحة عندما تكون الحالة أقل من 500. إذا حدث خطأ شبكي، يلتقطه الجسر ويُبلِغ بأن الخدمة غير متاحة بدلًا من طرح استثناء.

ملاحظة الإصدار

يصف هذا التوثيق الحزمة ضمن خط ^3.0 الخاص بها. يتطابق ذلك الخط مع متطلب composer.json ومصفوفة الدعم في SECURITY.md، حيث 3.⁨x⁩ مدعوم و2.⁨x⁩ غير مدعوم. الإشارات الأقدم إلى 0.x في صفحات الهيكل داخل المستودع تسبق خط 3.0. يَجُبّ قيد composer.json تلك الإشارات.

انظر أيضًا

• /⁨integrations/gotenberg/overview/⁩ — ما الذي يفعله الجسر وأي الصيغ يحوّلها.
• /⁨integrations/gotenberg/configuration/⁩ — كل وسيطة مُنشئ وكل حقل تهيئة.
• /⁨integrations/gotenberg/quickstart/⁩ — تحويل أول كامل وقابل للتشغيل.
• /⁨integrations/gotenberg/security-and-operations/⁩ — كيفية تشغيل تبعية ⁨Gotenberg⁩ بأمان.
• /⁨integrations/gotenberg/boot-and-discovery/⁩ — التوصيل التلقائي لإطار العمل.