البدء السريع مع NextPDF Gotenberg

لمحة سريعة

يحوّل هذا الدليل العملي ملف .docx واحدًا إلى تنسيق المستندات المحمولة (⁨PDF⁩). عند الانتهاء، ستحصل على ثلاثة أشياء: مثيل جسر عامل، واتصال خدمة تم التحقق منه، وملف ⁨PDF⁩ محفوظ على القرص. يوجد البرنامج الكامل في المستودع عند examples/convert-office-to-pdf.php. المقتطفات التالية مأخوذة من ذلك البرنامج.

يبدأ هذا الدرس التعليمي بأبسط مسار عملي. تُغطّى موضوعات الإنتاج، بما في ذلك مصادر الأسرار وإعادة المحاولات والمُهَل وقابلية المراقبة، في /⁨integrations/gotenberg/production-usage/.⁩

قبل أن تبدأ

قبل المتابعة، تأكّد من هذه الأمور الثلاثة:

1. شغّلت composer require nextpdf/gotenberg، وثبّت عميل توصية معايير ⁨PHP⁩ ‏(⁨PSR⁩)-18 بالإضافة إلى مصانع ⁨PSR-17.⁩ راجع /⁨integrations/gotenberg/install/.⁩
2. خدمة ⁨Gotenberg⁩ متاحة عبر بروتوكول نقل النص التشعبي الآمن (⁨HTTPS⁩). يرفض الجسر http:// العادي قبل أن يغادر أي طلب العملية.
3. لديك ملف عينة بأحد هذه التنسيقات: .docx، .xlsx، .pptx، .odt، .ods، أو .odp. تفشل أي امتدادات أخرى مع ValueError.

الخطوة 1 — وصف الخدمة

GotenbergConfig كائن قيمة غير قابل للتغيير. يحتاج، في الحد الأدنى، إلى عنوان ⁨URL⁩ الأساسي عبر ⁨HTTPS⁩ لخدمة ⁨Gotenberg⁩ لديك:

use NextPDF\Gotenberg\GotenbergConfig;

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

يطبّق وسيط النقل المستند إلى ⁨cURL⁩ القيمة timeout بصفتها مُهلة النقل بالثواني. عندما يكون apiKey غير فارغ، يرسله الجسر بصيغة Authorization: Bearer <token>. اترك apiKey فارغًا إذا كان نشر ⁨Gotenberg⁩ لديك لا يتطلّب رمزًا مميزًا.

الخطوة 2 — توصيل الجسر

مرّر التهيئة ومكوّنات ⁨PSR⁩ إلى الجسر. احقن أيضًا responseFactory لتمكين وسيط نقل ⁨cURL⁩ مع تثبيت نظام أسماء النطاقات (⁨DNS⁩) وأمان طبقة النقل (⁨TLS⁩):

use NextPDF\Gotenberg\GotenbergBridge;

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

لا ينشئ الجسر أبدًا عميل بروتوكول نقل النص التشعبي (⁨HTTP⁩) نيابةً عنك. استخدم عميل ⁨PSR-18⁩ ‏ومصانع ⁨PSR-17⁩ التي ثبّتها. يعرض ملف المثال طريقة توصيل ⁨Guzzle⁩ في تعليق.

الخطوة 3 — التحقق من التوافر

تحقّق من الخدمة قبل تحويل أي ملف. يتحقّق المسبار من صحة عنوان ⁨URL⁩ دون أي حركة مرور على الشبكة، ثم يرسل طلب HEAD إلى <apiUrl>/health:

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

في حالة عنوان ⁨URL⁩ فارغ أو غير آمن (⁨non-HTTPS⁩) أو ذي عنوان خاص، أو عند حدوث أي خطأ في الشبكة، تُعيد isAvailable() القيمة false (ولا تطرح استثناءً أبدًا). إذا كانت الحالة المُعادة من /health أقل من 500 فهذا يعني أن الخدمة متاحة.

الخطوة 4 — التحويل

استدعِ convertFile() بمسار على القرص. يحوّل الجسر المسار إلى صورته المعيارية لمنع اجتياز المسارات. يطابق الامتداد مع تنسيق مدعوم، ويتحقّق من الحجم واسم الملف، ثم يرسل طلبًا متعدد الأجزاء إلى <apiUrl>/forms/libreoffice/convert:

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $e;
} catch (\RuntimeException $e) {
    // Non-HTTPS URL, private address, oversized input, or unsafe filename.
    throw $e;
} catch (\ValueError $e) {
    // Extension is not one of the six recognised Office formats.
    throw $e;
}

لتحويل وحدات بايت موجودة بالفعل في الذاكرة، استخدم convertString(). مرّر اسم الملف الأصلي حتى يتمكّن الجسر من اكتشاف الامتداد:

$pdf = $bridge->convertString($docxBytes, 'report.docx');

الخطوة 5 — استخدام النتيجة

تتضمّن النتيجة ثلاثة أشياء: وحدات بايت ⁨PDF⁩، وتنسيق المصدر، وفحص الصلاحية:

if (! $result->isValid()) {
    throw new \RuntimeException('Result is not a valid PDF.');
}

\file_put_contents('/path/to/report.pdf', $result->pdfData);

\printf(
    "Converted %s (%d bytes)\n",
    $result->sourceFormat->value,
    $result->size(),
);

تكون isValid() صحيحة عندما يكون المحتوى غير فارغ ويبدأ بـ %PDF. تُعيد size() الطول بالبايت. من هنا، يصبح ملف ⁨PDF⁩ دفقًا عاديًا يمكنك تمريره إلى ⁨NextPDF⁩ للمعالجة اللاحقة.

البرنامج الكامل

يوجد البرنامج الكامل القابل للتشغيل في examples/convert-office-to-pdf.php ضمن مستودع الحزمة. يتضمّن تحليل الوسائط، والتهيئة المدفوعة بالبيئة، ومسبار السلامة، ومعالجة شاملة للأخطاء، وخطوة الكتابة. شغّله باستخدام:

GOTENBERG_URL=https://gotenberg.example.com \
php examples/convert-office-to-pdf.php report.docx report.pdf

ما التالي

• /⁨integrations/gotenberg/configuration/⁩ — راجع كل خيار وقواعد اختيار وسيط النقل.
• /⁨integrations/gotenberg/production-usage/⁩ — تعامل مع الأسرار وإعادة المحاولات والمُهَل والتسجيل والتزامن.
• /⁨integrations/gotenberg/troubleshooting/⁩ — افهم كل استثناء يمكن أن تطرحه هذه الشفرة وما يعنيه.
• /⁨integrations/gotenberg/integration/⁩ — شغّل خط أنابيب تصيير ⁨NextPDF⁩ عبر الخدمة.