إعداد NextPDF Gotenberg

نظرة سريعة

يتكوّن التكوين من جزأين: كائن القيمة غير القابل للتغيير GotenbergConfig الذي يصف الخدمة وحدودها، ومُنشئ GotenbergBridge الذي يتلقى المتعاونين المتوافقين مع توصيات ⁨PHP⁩ القياسية (⁨PSR⁩) والخاصة ببروتوكول نقل النص التشعبي (⁨HTTP⁩). يُمرَّر كلاهما صراحةً عبر حقن المُنشئ. لا تحتفظ الحزمة بأي حالة عامة، ولا تقرأ أي متغيرات بيئة، ولا تُعرّف أي نقطة نهاية افتراضية مخفية.

كائن التكوين

GotenbergConfig هو كائن قيمة من نوع final readonly. أنشئه مباشرةً باستخدام الوسيطات المُسمّاة، أو ابنِه من مصفوفة ترابطية باستخدام GotenbergConfig::fromArray().

الحقول

الحقل	النوع	الافتراضي	الأثر
apiUrl	string	''	محدّد موقع المورد الموحّد (⁨URL⁩) الأساسي لخدمة ⁨Gotenberg.⁩ مطلوب: تجعل القيمة الفارغة التكوين غير صالح، ويفشل كل تحويل سريعاً. يجب أن يستخدم بروتوكول نقل النص التشعبي الآمن (⁨HTTPS⁩).
timeout	int	30	المهلة الزمنية الصارمة للنقل بالثواني. يطبّقها النقل المثبَّت عبر ⁨cURL⁩ عند اختياره.
maxFileSize	int	52_428_800	الحد الأقصى لحجم الإدخال بالبايت (50 ⁨MiB⁩). تُرفض المدخلات الأكبر من ذلك قبل أي طلب.
apiKey	string	''	رمز ⁨Bearer⁩ المميّز. عندما يكون غير فارغ، يُرسَل كترويسة Authorization: Bearer <token>. وهو مُعلَّم بـ #[\SensitiveParameter] بحيث يُحجب في تتبّعات المكدّس.
pinnedPublicKeys	list<string>	[]	دبابيس ⁨SubjectPublicKeyInfo⁩ (⁨SPKI⁩) الأساسية لأمان طبقة النقل (⁨TLS⁩) بصيغة sha256/<base64>. القيمة الفارغة تعطّل التثبيت.
backupPublicKeys	list<string>	[]	دبابيس ⁨SPKI⁩ الاحتياطية لـ ⁨TLS⁩، وتُحفظ منفصلةً بحيث يمكن التحقق من التدوير بشكل مستقل.

الإنشاء المباشر

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

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

الإنشاء من مصفوفة

تقبل fromArray() المفاتيح بنمط ⁨snake_case⁩ وتتجاهل القيم المشوّهة بدلاً من إطلاق استثناء. تصبح قيمة api_url غير النصية ''. وتعود قيمة timeout غير الصحيحة إلى 30. وتعود قيمة max_file_size غير الصحيحة إلى القيمة الافتراضية البالغة 50 ⁨MiB.⁩ أما قوائم الدبابيس غير المصفوفية فتصبح []. وتُسقَط الإدخالات غير النصية داخل مصفوفات الدبابيس.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

هذا التحليل المتسامح مقصود. يمكنك تمرير مصفوفة تكوين إطار العمل مباشرةً، دون طبقة تحقق مسبق، وستحصل مع ذلك على كائن مضبوط النوع. وهي لا تتحقق من إمكانية الوصول إلى عنوان ⁨URL⁩ أو من صحة الدبابيس. يُجري الجسر تلك الفحوص وقت التحويل.

الصلاحية

تُرجع isValid() القيمة true فقط عندما تكون apiUrl سلسلة نصية غير فارغة. ولا تُجري أي فحوص للشبكة أو للمخطط. تتولى سياسة الأمان معالجة ⁨HTTPS⁩ وفحص العناوين الخاصة وقت التحويل. إذا كان التكوين غير صالح، تُطلق convertFile() وconvertString() استثناء GotenbergConvertException مع الرسالة Invalid Gotenberg configuration: apiUrl is empty. كذلك يجعل التكوين غير الصالح isAvailable() تُرجع false دون أي اتصال بالشبكة.

مُنشئ الجسر

يتلقى GotenbergBridge التكوين إلى جانب متعاوني ⁨PSR⁩:

الوسيطة	النوع	مطلوب	الأثر
config	GotenbergConfig	نعم	واصف الخدمة وحدودها الموضّحة سابقاً.
httpClient	Psr\Http\Client\ClientInterface	نعم	عميل ⁨PSR-18⁩ المستخدَم لفحص السلامة والنقل الاحتياطي.
requestFactory	Psr\Http\Message\RequestFactoryInterface	نعم	يبني طلب ⁨PSR-7.⁩
streamFactory	Psr\Http\Message\StreamFactoryInterface	نعم	يبني دفق جسم الطلب.
logger	Psr\Log\LoggerInterface|null	لا (الافتراضي null)	عند توفيره، يسجّل إدخالاً واحداً بمستوى debug لكل طلب تحويل.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	لا	يستخدم افتراضياً سياسة الأمان الأساسية للغة ترميز النص التشعبي (⁨HTML⁩). تُطبَّق في طبقة التحليل وتكمّل سياسة طبقة النقل.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	لا (الافتراضي null)	مطلوب لتفعيل النقل المثبَّت عبر ⁨cURL.⁩ بدونه يستخدم الجسر دائماً عميل ⁨PSR-18⁩ المحقون.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

اختيار النقل

يدعم الجسر نوعَي نقل، ويختار أحدهما لكل طلب تحويل:

• النقل المثبَّت عبر ⁨cURL⁩ — يُستخدم عندما يكون responseFactory قد حُقن و يوجد ما يمكن تثبيته (يتحلّل عنوان ⁨URL⁩ إلى عنوان أو أكثر من عناوين بروتوكول الإنترنت (⁨IP⁩)، أو تكون دبابيس ⁨SPKI⁩ مكوّنة). يربط هذا النقل مجموعة العناوين المُحلَّلة باستخدام CURLOPT_RESOLVE. ويفرض تثبيت ⁨SPKI⁩ باستخدام CURLOPT_PINNEDPUBLICKEY عند وجود دبابيس. ويتحقق من النظير والمضيف (CURLOPT_SSL_VERIFYPEER، CURLOPT_SSL_VERIFYHOST = 2). ويطبّق المهلة الزمنية المُكوَّنة ويعطّل اتّباع إعادة التوجيه (CURLOPT_FOLLOWLOCATION = false، CURLOPT_MAXREDIRS = 0).
• عميل ⁨PSR-18⁩ المحقون — يُستخدم في كل الحالات الأخرى، بما في ذلك عندما يكون عنوان ⁨URL⁩ لواجهة برمجة التطبيقات (⁨API⁩) عنوان ⁨IP⁩ عاماً صِرفاً (لا يوجد نظام أسماء النطاقات (⁨DNS⁩) للتثبيت) ولم تُكوَّن دبابيس ⁨SPKI⁩، أو عندما لا يُوفَّر responseFactory.

للاتصالات المقاومة لإعادة ربط ⁨DNS⁩ ولتثبيت ⁨TLS⁩، احقن responseFactory وكوّن الدبابيس. يستخدم فحص السلامة دائماً عميل ⁨PSR-18⁩ المحقون، أياً كان النقل المختار.

تثبيت المفتاح العام لـ ⁨TLS⁩

يستخدم التثبيت نموذج بصمة ⁨SPKI⁩ القائم على خوارزمية التجزئة الآمنة 256-بت (⁨SHA-256⁩). كل دبوس سلسلة نصية بالصيغة sha256/<base64-encoded-spki-hash>. يقبل النقل أيضاً الصيغة الأصلية في ⁨cURL⁩ sha256//<base64> ويحوّل صيغة الشرطة المائلة الواحدة إليها. أي بادئة أخرى تُطلق InvalidSpkiPinException.

تُرجع allPublicKeyPins() اتحاد pinnedPublicKeys وbackupPublicKeys بعد إزالة التكرار. تقبل طبقة ⁨TLS⁩ أي شهادة تطابق تجزئة ⁨SPKI⁩ الخاصة بها أي عضو من تلك المجموعة المدمجة. لأغراض التشغيل، كوّن دبوساً احتياطياً واحداً على الأقل بحيث لا يؤدي تدوير مخطَّط لشهادة أو مفتاح إلى حجب الجسر عن الخدمة أثناء انتشار المفتاح الجديد. إبقاء القائمة الاحتياطية منفصلة عن القائمة الأساسية يتيح لك التحقق من الدبوس الاحتياطي وتدويره بشكل مستقل عن الدبوس النشط. راجع /⁨integrations/gotenberg/security-and-operations/⁩ للاطّلاع على إجراء التدوير.

خيارات التحويل لكل طلب

يحمل نوع الحمولة متعددة الأجزاء (GotenbergConvertPayload) الملف إضافةً إلى خيارَي تحويل ⁨Gotenberg⁩ اختياريين:

• landscape (bool، الافتراضي false) — يُرسَل كحقل النموذج landscape بقيمة "true" أو "false".
• nativePageRanges (string، الافتراضي '') — يُرسَل كحقل النموذج nativePageRanges فقط عندما يكون غير فارغ؛ يقبل صيغة النطاقات في ⁨Gotenberg⁩، مثل 1-3 أو 1,3,5-9.

تبني نقطتا الدخول العامتان convertFile() وconvertString() الحمولة بالقيم الافتراضية لكلا الحقلين. الحقلان جزء من عقد الحمولة، وتختبرهما مجموعة الاختبارات. اكشفهما من طبقة التكامل لديك إذا احتجت إلى إخراج أفقي أو إلى تحديد الصفحات.

انظر أيضاً

• /⁨integrations/gotenberg/install/⁩ — التثبيت والأساس المرجعي لـ ⁨Gotenberg.⁩
• /⁨integrations/gotenberg/quickstart/⁩ — مثال شامل قابل للتشغيل من البداية إلى النهاية.
• /⁨integrations/gotenberg/production-usage/⁩ — مصادر التكوين والأسرار والمهل الزمنية وإعادة المحاولات.
• /⁨integrations/gotenberg/security-and-operations/⁩ — نموذج الأمان الكامل وتدوير الدبابيس.
• /⁨integrations/gotenberg/troubleshooting/⁩ — معاني الاستثناءات المتعلقة بالتكوين.