تكامل NextPDF مع Cloudflare

نظرة سريعة

تعرض هذه الصفحة مسار ⁨Cloudflare⁩ الكامل: ثبّت الحزمة، واضبطها، وصيّر ملف ⁨Portable Document Format⁩ ‏(⁨PDF⁩)، وأرشِف النتيجة اختيارياً. تمر عملية التصيير في كل خطوة عبر ⁨Cloudflare Worker⁩ و⁨R2.⁩ استخدم هذا الدليل الإرشادي مع الصفحة المفاهيمية /⁨integrations/cloudflare/overview/⁩ والمرجع /⁨integrations/cloudflare/configuration/.⁩

التثبيت

composer require nextpdf/cloudflare:^0.1

بعد ذلك، أضف عميل ⁨PHP Standards Recommendation⁩ ‏(⁨PSR⁩)-18 ومصانع ⁨PSR-17⁩، مثل ⁨Guzzle 7.⁩ لا تصرّح الحزمة إلا بعقود ⁨PSR⁩ ولا تتضمن أي تنفيذ عميل فعلي، لذا وفّر واحداً. للاطلاع على التفاصيل الكاملة، راجع /⁨integrations/cloudflare/install/.⁩

الإقلاع / الاكتشاف التلقائي

لا يتضمن الجسر أي مزود خدمة ولا أي حزمة. أنشئه مباشرة من المتعاونين المتوافقين مع ⁨PSR⁩ ومن CloudflareRendererConfig. ينبغي لإطار العمل المضيف أن يربطه داخل حاويته مع إعادة استخدام ارتباط ⁨PSR-18⁩ الموجود في التطبيق. للاطلاع على تسلسل الإقلاع الكامل ومثال على ارتباط الحاوية، راجع /⁨integrations/cloudflare/boot-and-discovery/.⁩

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

اربط CloudflareHtmlRenderer ككائن مفرد (⁨singleton⁩). مرّر عميل ⁨PSR-18⁩، ومصنعَي الطلب والدفق من ⁨PSR-17⁩، ومسجّل ⁨PSR-3⁩ اختيارياً. عند استخدام ناقل ⁨cURL⁩ المثبّت، مرّر أيضاً مصنع استجابة ⁨PSR-17.⁩ راجع مثال الارتباط في /⁨integrations/cloudflare/boot-and-discovery/.⁩

نشر الإعدادات

تقرأ الحزمة الإعدادات من CloudflareRendererConfig. حمّل الأسرار من البيئة، ولا تحملها أبداً من الملفات المودَعة في المستودع:

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => getenv('CF_WORKER_URL') ?: '',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => getenv('CF_R2_FONT_BUCKET') ?: null,
]);

يجب أن يستخدم workerUrl مخطط ⁨Hypertext Transfer Protocol Secure⁩ ‏(⁨HTTPS⁩). apiToken موسوم بـ #[SensitiveParameter]. للاطلاع على مرجع الحقول الكامل، راجع /⁨integrations/cloudflare/configuration/⁩، فهو يغطي حقول تثبيت ⁨Subject Public Key Info⁩ ‏(⁨SPKI⁩) وكل القيم الافتراضية. تجد إعدادات الأرشفة في ⁨R2⁩ وطبقة حماية ⁨application programming interface⁩ ‏(⁨API⁩) موضحة في /⁨integrations/cloudflare/production-usage/.⁩

اختبار الدخان لمزود الخدمة / الحزمة

لا يوجد مزود خدمة تُجري عليه اختبار دخان. استخدم فحص الإقلاع هذا بدلاً من ذلك:

$config = CloudflareRendererConfig::fromArray($appConfig['cloudflare']);
assert($config->isValid(), 'Cloudflare config incomplete');

// Optional runtime reachability check (authenticated HTTP HEAD):
if (!$renderer->isAvailable()) {
    // Worker not reachable — degrade or alert.
}

isValid() فحص اكتمال فقط ولا يُجري أي اتصال بالشبكة. isAvailable() يُنفّذ طلب HEAD مُصادَقاً عليه. يعيد false دون طرح استثناء عندما يكون الـ ⁨Worker⁩ متوقفاً.

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

تكشف الحزمة هذا السطح العام ضمن NextPDF\Cloudflare\:

النوع	الدور
`CloudflareHtmlRenderer`	نقطة دخول التصيير: `render()`، `isAvailable()`، `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	إعدادات المُصيِّر (`fromArray()`، `isValid()`، `allPublicKeyPins()`).
`CloudflareRenderResult`	نتيجة تصيير ذات نوع محدّد (`isValid()`، `size()`).
`CloudflareRenderPayload`	حمولة ⁨JavaScript Object Notation⁩ ‏(⁨JSON⁩) الخاصة بالـ ⁨Worker⁩ (`toJson()`).
`CloudflareResponseParser`	محلّل يحوّل استجابة الـ ⁨Worker⁩ ← إلى النتيجة.
`CloudflareSecurityPolicy`	التحقق من المدخلات وعناوين ⁨URL.⁩
`Transport\PinnedCurlTransport`	ناقل ⁨PSR-18⁩ مع تثبيت ⁨Domain Name System⁩ ‏(⁨DNS⁩) ‏/ ‏⁨Transport Layer Security⁩ ‏(⁨TLS⁩).
`Contract\LocalRendererFactoryInterface`، `Contract\LocalRendererInterface`	عقود الاحتياط المحلي.
`ApiProtection`، `ApiProtectionConfig`، `ApiProtectionResult`، `ApiKeyValidator`	حماية ⁨API⁩ الواردة.
`R2ArchiveManager`، `R2ArchiveConfig`، `R2ObjectKey`، `R2UploadResult`	الأرشفة في ⁨R2.⁩
`Exception\CloudflareRenderException`، `Exception\CloudflareNotAvailableException`، `Exception\InvalidSpkiPinException`	التسلسل الهرمي للاستثناءات.

للاطلاع على شرح كامل لعملية التصيير، راجع /⁨integrations/cloudflare/quickstart/.⁩ وللاطلاع على الربط في بيئة الإنتاج، راجع /⁨integrations/cloudflare/production-usage/⁩، فهو يغطي الاحتياط والقياس عن بُعد والأرشفة والحماية.

انظر أيضاً

/⁨integrations/cloudflare/overview/⁩ — حدود الثقة ونموذج التصيير عند الحافة.
/⁨integrations/cloudflare/quickstart/⁩ — أول عملية تصيير قابلة للتشغيل.
/⁨integrations/cloudflare/boot-and-discovery/⁩ — تفاصيل ربط الحاوية.
/⁨integrations/cloudflare/security-and-operations/⁩ — الدفاع ضد تزوير الطلبات من جانب الخادم (⁨SSRF⁩)، والتثبيت، ودليل التشغيل التنفيذي.
/⁨integrations/cloudflare/troubleshooting/⁩ — أنماط الإخفاق المرتبطة بالاستثناءات.