دليل مطوِّر Gotenberg

لمحة سريعة

ترسل حزمة ⁨Gotenberg⁩ عمليات تحويل المستندات إلى تنسيق المستندات المحمولة (⁨PDF⁩) إلى خدمة خارجية. في شيفرة التطبيق، أبقِ حدود الخدمة واضحة: تحقَّق من المدخلات، وابنِ الحمولة، وأرسل الطلب، وحلِّل النتيجة، وعالِج فشل الخدمة.

استخدم هذا الدليل عند إنشاء سير عمل لتحويل المستندات المكتبية إلى ⁨PDF⁩، أو نقاط نهاية للرفع، أو فحوص سلامة الخدمة، أو سياسة النقل حول nextpdf/gotenberg.

حدود البنية

الطبقة	مملوكة لـ	المسؤولية	لا تضع هنا
مصدر الرفع أو المستند	التطبيق	تحقَّق من صلاحية المُستدعي، وتحقَّق من المصدر، واختر سياسة التحويل.	قرارات نقطة نهاية الخدمة أو تثبيت النقل.
اكتشاف التنسيق	`nextpdf/gotenberg`	اربط الامتدادات الآمنة بـ `OfficeFormat`.	الثقة في أنواع الوسائط المُعلَنة دون تحقُّق على مستوى التطبيق.
الجسر	`nextpdf/gotenberg`	أنشئ الطلب متعدد الأجزاء، واستدعِ ⁨Gotenberg⁩، وحلِّل استجابة ⁨PDF.⁩	استعلامات المجال أو سياسة التخزين.
خدمة ⁨Gotenberg⁩	النشر	حوِّل المستند المكتبي إلى ⁨PDF.⁩	تصريح تطبيق ⁨PHP⁩.
المحرك الأساسي	`nextpdf/nextpdf`	استورد بيانات ⁨PDF⁩ المُحوَّلة أو ادمجها عند الحاجة.	التحويل المكتبي.

دورة حياة وقت التشغيل

المرحلة	السلوك	إجراء المطوِّر
إنشاء التهيئة	تُحمَّل نقطة نهاية واجهة برمجة التطبيقات (⁨API⁩)، والمهلة، والحجم الأقصى، ومفتاح ⁨API⁩، والتثبيتات من التهيئة.	أبقِ نقطة نهاية الخدمة والرمز المميز خارج الشيفرة المصدرية.
التحقُّق من المدخلات	يُتحقَّق من مسار الملف، وحجم الملف، واسم الملف، والامتداد، وسلامة محدِّد موقع المورد الموحَّد (⁨URL⁩).	ارفض المدخلات غير المدعومة قبل إرسالها.
بناء الحمولة	يبني `GotenbergConvertPayload` بيانات النموذج متعددة الأجزاء.	احتفظ باسم الملف الأصلي فقط عندما يكون آمنًا.
طلب الخدمة	يرسل الجسر الطلب إلى `/forms/libreoffice/convert`.	هيِّئ المهلة وسياسة النقل.
تحليل النتيجة	تُرجِع `GotenbergResponseParser::parse()` بايتات ⁨PDF⁩ وبيانات وصفية.	تعامل مع الاستجابات غير ⁨PDF⁩ واستجابات الأخطاء على أنها حالات فشل تحويل.

بنية التطبيق الموصى بها

المسار	الغرض
`app/Pdf/Conversion/*`	غلاف على مستوى التطبيق حول `GotenbergBridge`.
`app/Pdf/Uploads/*`	التحقُّق من الرفع، والتخزين، وسياسة تسمية الملفات.
`app/Pdf/ConversionPolicy/*`	سياسة الحجم والتنسيق واختيار الخدمة.
`tests/Pdf/Conversion/*`	اختبارات التنسيق والملفات والخدمة والنقل.

افصل التحقُّق من الملفات عن التحويل. ينبغي أن تتلقى خدمة التحويل لديك مدخلات مُصرَّحًا بها مسبقًا، ثم تبقى معتمدة على تحقُّق الحزمة بوصفه دفاعًا متعمِّقًا.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

        if (!$result->isValid()) {
            throw new RuntimeException('The conversion service did not return a valid PDF.');
        }

        return $result->pdfData;
    }
}

أنماط التحويل

النمط	⁨API⁩	استخدمه عندما	القيد
تحويل مسار ملف	`GotenbergBridge::convertFile()`	عندما يكون المستند مخزَّنًا بالفعل على القرص.	يجب أن يكون المسار قابلًا للقراءة ومُعتمدًا وفق السياسة.
تحويل بايتات في الذاكرة	`GotenbergBridge::convertString()`	عندما يمتلك تطبيقك بالفعل بايتات من عملية رفع أو من مخزن كائنات.	لا يزال اسم الملف يتحكم في اكتشاف التنسيق.
بناء الحمولة مباشرة	`GotenbergConvertPayload`	عندما تحتاج إلى بايتات متعددة الأجزاء للاختبارات أو لشيفرة نقل مخصَّصة.	أبقِ توليد الحدود الفاصلة بعيدًا عن مدخلات المستخدم.
تحليل الاستجابة مباشرة	`GotenbergResponseParser::parse()`	لا تزال استدعاءات بروتوكول نقل النصوص الفائقة (⁨HTTP⁩) المخصَّصة بحاجة إلى تحليل الحزمة.	يجب أن تُمرِّر `OfficeFormat` المتوقَّع.

السلامة والجاهزية

GotenbergBridge::isAvailable() إشارة جاهزية، وليست خط دفاعك الوحيد في وقت التشغيل. يمكن أن تجتاز الخدمة فحص الجاهزية ومع ذلك تفشل في التحويل التالي.

الفحص	الغرض	ملاحظة تشغيلية
صحة التهيئة	اكتشف غياب نقطة نهاية ⁨API.⁩	شغِّل هذا أثناء إقلاع التطبيق أو فحوص النشر.
توافر `/health`	اكتشف ما إذا كانت الخدمة قابلة للوصول.	استخدم هذا في لوحات معلومات الجاهزية.
تحويل ملف اختبار صغير	اكتشف سلوك ⁨LibreOffice⁩ المتعطِّل أو تراجع أداء الخدمة.	شغِّل هذا في اختبارات الدخان المجدولة، لا في كل طلب.
مراقبة المهلة	اكتشف بطء سلوك الخدمة.	تتبَّع هذا حسب التنسيق وحجم الملف.

نقاط التوسعة

نقطة التوسعة	استخدمها من أجل	القيد
توصية معيار ⁨PHP⁩ (⁨PSR⁩)-18 `ClientInterface`	سلوك عميل ⁨HTTP⁩ مخصَّص.	يجب أن يتبع دلالات الاستجابة والاستثناءات في ⁨PSR-18.⁩
مصانع ⁨PSR-17⁩	إنشاء الطلب والدفق.	مطلوبة لبناء الجسر.
`HtmlSecurityPolicyInterface`	سياسة على مستوى المُحلِّل لمدخلات لغة ترميز النصوص الفائقة (⁨HTML⁩).	تُكمِّل سياسة أمان ⁨Gotenberg.⁩
`ResponseFactoryInterface`	بناء استجابة نقل ⁨cURL⁩ المثبَّت.	مطلوبة فقط عند استخدامك مسار نقل الحزمة.
`GotenbergSecurityPolicy`	التحقُّق من ⁨URL⁩، وحجم الملف، واسم الملف، والتثبيت.	أبقِ تصريح التطبيق خارج هذه الطبقة.

سير عمل التطوير

ابدأ بـ convertString() في الاختبارات لإبقاء ملفات الاختبار صريحة.
أضف convertFile() فقط بعد التحكُّم في مسارات نظام الملفات.
أبقِ الحجم الأقصى للملف دون حدود الخدمة والبنية التحتية.
استخدم isAvailable() لإشارات الجاهزية، وليس بديلًا عن معالجة الأخطاء.
سجِّل اسم الملف، والتنسيق، والحجم، والحالة، والمدة. لا تسجِّل بايتات المستند.
أضف اختبارات المهلة وأوضاع الفشل قبل أن تكشف نقاط نهاية الرفع.

معالجة الفشل

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

الإعدادات الافتراضية الآمنة

الجانب	الافتراضي	متى تتجاوزه
المهلة	`30` ثانية.	زِدها فقط بعد أن تقيس زمن استجابة الخدمة الفعلي.
الحجم الأقصى للملف	`52,428,800` بايت.	خفِّضه لنقاط النهاية العامة أو متعددة المستأجرين.
مفتاح ⁨API⁩	فارغ.	عيِّنه لعمليات نشر ⁨Gotenberg⁩ الخاصة.
التنسيقات المدعومة	`docx`، `xlsx`، `pptx`، `odt`، `ods`، `odp`.	أضف تنسيقات فقط عندما يدعمها `OfficeFormat` والمُحلِّل.
مجموعات التثبيت	فارغة.	أضف تثبيتات مع تثبيتات احتياطية وإجراء تدوير.

قائمة فحص الاختبار

تغطي اختبارات التنسيق الامتدادات المدعومة وغير المدعومة.
تغطي اختبارات الملفات الملفات المفقودة، والملفات غير القابلة للقراءة، والملفات بحجم مفرط، وأسماء الملفات غير الآمنة.
تغطي اختبارات الخدمة الاستجابات غير 2⁨xx⁩، وأجسام الاستجابات غير الصالحة، واستثناءات النقل.
تغطي اختبارات الأمان عناوين ⁨URL⁩ الخاصة أو غير الصالحة للخدمة عندما تحظرها السياسة.
تؤكِّد اختبارات المهلة أن المهلة المُهيَّأة تُمرَّر إلى النقل.
تُبقي اختبارات ملفات الاختبار المستندات النموذجية صغيرة وغير حساسة.