تكامل NextPDF مع Gotenberg

لمحة سريعة

توضّح هذه الصفحة كيفية ربط الجسر ببقية تطبيقك. ثبّته واربطه، ثم مرّر ملف ⁨Portable Document Format⁩ (⁨PDF⁩) المحوَّل إلى مسار المعالجة اللاحقة في ⁨NextPDF.⁩ يحوّل الجسر مستند ⁨Office⁩ إلى ⁨PDF⁩، ويتولّى مسار المعالجة كل ما يلي التحويل. للاطّلاع على التصميم الذي يستند إليه هذا الربط، راجع /⁨integrations/gotenberg/boot-and-discovery/.⁩

التثبيت

composer require nextpdf/gotenberg

يؤدّي تثبيت هذه الحزمة أيضًا إلى تثبيت nextpdf/core ^3.0 وعقود ⁨PHP Standards Recommendation⁩ (⁨PSR⁩) الخاصة بـ ⁨Hypertext Transfer Protocol⁩ (⁨HTTP⁩). ثبّت عميل ⁨PSR-18⁩ ومصانع ⁨PSR-17⁩ كحزم منفصلة. يعتمد الجسر على الواجهات فقط، لذلك يمكنك اختيار المكتبات الفعلية بنفسك. للاطّلاع على خطوات التثبيت الكاملة، بما في ذلك تشغيل خدمة ⁨Gotenberg⁩ عبر ⁨Hypertext Transfer Protocol Secure⁩ (⁨HTTPS⁩)، راجع /⁨integrations/gotenberg/install/.⁩

الربط

أنشئ الجسر باستخدام كائن إعدادات ومتعاوني ⁨PSR.⁩ احقن أيضًا مصنع استجابة، فهو يفعّل النقل المعتمد على تثبيت ⁨Domain Name System⁩ (⁨DNS⁩) وتثبيت ⁨Transport Layer Security⁩ (⁨TLS⁩):

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

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

يتطلّب الجسر استخدام ⁨HTTPS⁩ لعنوان ⁨URL⁩ المُعَد. ويرفض http:// العادي قبل إرسال أي طلب. شغّل ⁨Gotenberg⁩ خلف إنهاء ⁨TLS⁩، ثم وجّه الجسر إلى نقطة النهاية عبر ⁨HTTPS.⁩

روابط الحاوية

سجّل ثلاثة مدخلات في الحاوية المضيفة: GotenbergConfig المبني من مصدر إعداداتك، وعميل ⁨PSR-18⁩ لديك مع مصانع ⁨PSR-17⁩، وGotenbergBridge المربوط بهذه التبعيات. لا توفّر هذه الحزمة روابط خاصة بها. يوجد التسجيل الأصلي لإطار العمل ضمن حزم تكامل إطار العمل المخصّصة. راجع /⁨integrations/gotenberg/boot-and-discovery/.⁩

الإعدادات

توجد جميع حقول واصف الخدمة وحدودها في GotenbergConfig. وتشمل عنوان ⁨URL⁩ لواجهة برمجة التطبيقات ⁨application programming interface⁩ (⁨API⁩)، والمهلة الزمنية، والحد الأقصى للحجم، ورمز الحامل، وتثبيتات ⁨TLS.⁩ أما خيارات كل طلب على حدة، وهي landscape وnativePageRanges، فتوجد على نوع الحمولة بدلاً من ذلك. يوثّق /⁨integrations/gotenberg/configuration/⁩ كل حقل، مع نوعه وقيمته الافتراضية وأثره.

ربط ملف ⁨PDF⁩ المحوَّل بمسار معالجة ⁨NextPDF⁩

تدفّق نموذجي من البداية إلى النهاية:

1. حوّل مستند ⁨Office⁩ باستخدام convertFile() أو convertString().
2. استخدم $result->pdfData، الذي يحتوي على بايتات ⁨PDF⁩ الخام، وحمّله في مستند ⁨NextPDF.⁩
3. طبّق المعالجة اللاحقة، مثل تجميع الصفحات، أو إضافة العلامة المائية، أو التحويل إلى ⁨PDF/A⁩، أو التوقيعات الرقمية.

تخص الخطوة 3 ⁨NextPDF⁩، لا الجسر. توفّر حزمة nextpdf/premium التوقيع، وملفات تعريف ⁨PDF/A⁩، وإضافة العلامة المائية. أبقِ التحويل والمعالجة اللاحقة مرحلتين منفصلتين كي تتمكّن من تشخيص كل عطل على حدة.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

إن دعم التوقيعات الإلكترونية المتقدمة لـ ⁨PDF⁩ (⁨PAdES⁩) في إصدار ⁨Pro⁩ يقتصر على الخط الأساسي ⁨B-B⁩ فقط. وهو لا يوفّر ⁨B-T⁩ أو ⁨B-LT⁩ أو ⁨B-LTA.⁩ ولا يعني تحويل مستند عبر هذا الجسر توفّر أي إمكانية للطابع الزمني أو التحقّق طويل الأمد.

اختبار الدخان

بعد الربط، تحقّق من التكامل دون تحويل مستند فعلي:

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

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

نقاط دخول ⁨API⁩ العامة

الواجهة العامة التي يستخدمها هذا التكامل:

• GotenbergConfig — واصف خدمة غير قابل للتغيير مع حدوده؛ يبنيه fromArray() من مصفوفة إعدادات.
• GotenbergBridge::convertFile(string $path) — يحوّل ملفًا على القرص.
• GotenbergBridge::convertString(string $bytes, string $fileName) — يحوّل بايتات محفوظة في الذاكرة.
• GotenbergBridge::isAvailable() — فحص جاهزية لا يطلق استثناءً.
• GotenbergConvertResult — يحمل pdfData وsourceFormat وisValid() وsize().
• GotenbergConvertException — نوع الاستثناء في طبقة التحويل.

يوجد العقد الكامل في /⁨integrations/gotenberg/configuration/⁩ و/⁨integrations/gotenberg/troubleshooting/.⁩ ويغطّي اختيار النقل وكتالوج الاستثناءات.

انظر أيضًا

• /⁨integrations/gotenberg/boot-and-discovery/⁩ — سبب ظهور الربط بهذا الشكل.
• /⁨integrations/gotenberg/quickstart/⁩ — أول تحويل موجَّه خطوة بخطوة.
• /⁨integrations/gotenberg/production-usage/⁩ — الأسرار، وإعادة المحاولة، والمهل الزمنية، وقابلية الرصد.
• /⁨integrations/gotenberg/install/⁩ — تثبيت الحزمة وخدمة ⁨Gotenberg.⁩