إقلاع NextPDF Cloudflare وآلية اكتشافه

لمحة سريعة

لا يوفّر الجسر أي مزود خدمة أو حزمة أو خطّاف اكتشاف تلقائي خاص به. فهو مجموعة من فئات final ذات بانيات صريحة. ويعني “الاكتشاف” هنا اختيار المتعاونين الذين ستحقنهم وربطهم في حاوية إطار العمل. توضّح هذه الصفحة هذا التوصيل، ولا تفترض آلية تسجيل ليست موجودة في الحزمة.

كيف يُكتشَف جسر العارض

ابنِ CloudflareHtmlRenderer؛ فهو لا يُكتشَف تلقائيًا. تبعياته هي عقود توصية ⁨PHP⁩ القياسية (⁨PSR⁩): ⁨PSR-18⁩ و⁨PSR-17⁩ و⁨PSR-3⁩، إلى جانب أنواع التهيئة والعقود الخاصة بالحزمة نفسها. يستطيع أي إطار عمل قادر على بناء هؤلاء المتعاونين أن يبني العارض. تعتمد الحزمة على عقود ⁨PSR⁩ فقط؛ ويؤكّد اختبار tests/Unit/Architecture/PsrConformanceTest.php عدم اقتران العارض بأي عميل ملموس. يستطيع تطبيقك المضيف إعادة استخدام ربط عميل ⁨HTTP⁩ الموجود لديه دون تعديل. وتعيد محوّلات ⁨NextPDF⁩ الخاصة بـ ⁨Laravel⁩ و⁨Symfony⁩ و⁨CodeIgniter⁩ استخدام ربط ⁨PSR-18⁩ نفسه. لا تضيف هذه الحزمة أي حزمة إطار عمل خاصة بها.

تسلسل الإقلاع

اتبع هذا الترتيب في حلّ المتعاونين، بما يطابق بانية CloudflareHtmlRenderer:

1. استخرج ClientInterface من ⁨PSR-18⁩ عبر ربط عميل ⁨HTTP⁩ الموجود في التطبيق.
2. استخرج RequestFactoryInterface وStreamFactoryInterface من ⁨PSR-17⁩؛ واستخرج أيضًا ResponseFactoryInterface عندما تريد ناقل ⁨cURL⁩ المثبَّت.
3. ابنِ CloudflareRendererConfig من التهيئة المحلولة (انظر “ترتيب حلّ التهيئة”).
4. اختياريًا، استخرج LoggerInterface من ⁨PSR-3⁩، ووفّر LocalRendererFactoryInterface وHtmlSecurityPolicyInterface صراحةً.
5. ابنِ CloudflareHtmlRenderer بهؤلاء المتعاونين.

لا تُجري أي خطوة من هذه الخطوات اتصالًا بالشبكة. يحدث أول تفاعل مع الشبكة عند استدعائك render() أو isAvailable().

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

ربط تمثيلي (شِبه شِفرة محايدة لإطار العمل):

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Psr\Log\LoggerInterface;

$container->singleton(CloudflareHtmlRenderer::class, function ($c) {
    return new CloudflareHtmlRenderer(
        config:          CloudflareRendererConfig::fromArray($c->get('config')['cloudflare']),
        httpClient:      $c->get(ClientInterface::class),
        requestFactory:  $c->get(RequestFactoryInterface::class),
        streamFactory:   $c->get(StreamFactoryInterface::class),
        logger:          $c->get(LoggerInterface::class),
        responseFactory: $c->get(ResponseFactoryInterface::class),
    );
});

ترتيب حلّ التهيئة

لا تقرأ الحزمة متغيرات البيئة بنفسها؛ بل تقبل CloudflareRendererConfig مكتملة التكوين. في التطبيق المضيف، اتبع هذا الترتيب في حلّ التهيئة: متغيرات البيئة أولًا، ثم التهيئة المنشورة أو تهيئة إطار العمل، ثم الإعدادات الافتراضية للحزمة المضمَّنة في البانية (موثَّقة في /⁨integrations/cloudflare/configuration/⁩). تطبّق CloudflareRendererConfig::fromArray() الإعدادات الافتراضية للبانية على أي مفتاح غائب أو ذي نوع غير صحيح، فتعود مصفوفة التهيئة الجزئية إلى القيم الافتراضية بصورة متوقعة بدلًا من الإخفاق.

التشخيصات

CloudflareRendererConfig::isValid() هي إشارة وقت الإقلاع. وهي فحص خالص يتحقق من أن كلًّا من workerUrl وapiToken غير فارغين، ولا تُجري أي استدعاء للشبكة، لذلك يمكنك استخدامها بوابة نشر. إشارة وقت التشغيل هي CloudflareHtmlRenderer::isAvailable()، وهي طلب ⁨HTTP⁩ HEAD مُصادَق عليه يُعيد true لأي حالة دون 500 وfalse (دون أن يطرح استثناءً أبدًا) في غير ذلك، لذلك يمكنك استخدامها مسبار جاهزية. نجاح المسبار تلميح لا ضمان؛ إذ قد يظل طلب POST اللاحق قابلًا للإخفاق.

انظر أيضًا

• /⁨integrations/cloudflare/integration/⁩ — الشرح الكامل للتكامل خطوةً بخطوة.
• /⁨integrations/cloudflare/overview/⁩ — ماهية الجسر والحد الذي يعبره.
• /⁨integrations/cloudflare/configuration/⁩ — كل حقل وكل قيمة افتراضية.
• /⁨integrations/cloudflare/security-and-operations/⁩ — متى يُفعَّل الناقل المثبَّت.