دليل مطوّري Cloudflare

نظرة سريعة

تنقل حزمة ⁨Cloudflare⁩ تصيير صيغة المستندات المحمولة (⁨PDF⁩) إلى حدّ ⁨Worker.⁩ تعامَل مع تصيير ⁨Worker⁩، والاحتياط المحلي، وحماية واجهة برمجة التطبيقات (⁨API⁩)، وأرشيف ⁨R2⁩ بوصفها قدرات منفصلة، لكل منها معالجة الأعطال الخاصة بها.

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

حدود المعمارية

الطبقة	مملوكة من	المسؤولية	ما لا يُوضع هنا
نقطة نهاية التطبيق	التطبيق	صرّح للمستدعي، وطبّع طلب التصيير، وافرِض سياسة العمل.	رموز ⁨Worker⁩ المميزة المخزَّنة داخل الشيفرة.
حماية ⁨API⁩	nextpdf/cloudflare والتطبيق	فحوص مفتاح ⁨API⁩، وفحوص حجم الحمولة، وقرارات تحديد المعدّل داخل العملية.	الفوترة، أو استحقاق المستأجر، أو فرض الحصص الدائمة.
مُصيّر ⁨Cloudflare⁩	nextpdf/cloudflare	تحقَّق من لغة ترميز النص الفائق (⁨HTML⁩) ومن محدِّد موقع الموارد الموحَّد (⁨URL⁩) الخاص بـ ⁨Worker⁩، وأرسل حمولة التصيير، وحلِّل الاستجابة.	تصيير القوالب أو استعلامات المجال.
⁨Worker⁩	نشر التطبيق	شغّل التصيير عبر المتصفح وأعِد بايتات ⁨PDF⁩ أو نتيجة مُهيكَلة.	سياسة التخزين من جانب ⁨PHP.⁩
الاحتياط المحلي	نشر التطبيق	صيّر عندما يكون ⁨Worker⁩ غير متاح.	احتياط صامت يخفي الأعطال التشغيلية.
أرشيف ⁨R2⁩	nextpdf/cloudflare	ارفع ملفات ⁨PDF⁩، وابنِ مفاتيح الكائنات، وأنشئ عناوين ⁨URL⁩ موقَّعة.	بيانات وصفية حسّاسة للأعمال دون مراجعة.

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

المرحلة	السلوك	إجراء المطوّر
إنشاء الإعدادات	يحمّل عنوان ⁨URL⁩ الخاص بـ ⁨Worker⁩، ورمز ⁨API⁩ المميز، والمهل، وحدود الحجم، والاحتياط، والتثبيتات.	احتفظ بالأسرار ضمن إعدادات النشر.
حماية الطلب	تتحقَّق ApiProtection الاختيارية من المفتاح، والحجم، وحدّ المعدّل.	شغّلها قبل أعمال التصيير المكلفة.
استدعاء المُصيّر	تتحقَّق CloudflareHtmlRenderer من ⁨HTML⁩ ومن عنوان ⁨URL⁩ الخاص بـ ⁨Worker⁩، ثم ترسل ترميز كائنات ⁨JavaScript⁩ (⁨JSON⁩).	عالِج عدم توافر ⁨Worker⁩ وأعطال التصيير كلّاً على حدة.
تحليل الاستجابة	تقبل CloudflareResponseParser::parse() مُخرجات ⁨PDF⁩ الثنائية أو مُخرجات ⁨JSON⁩ المُهيكَلة.	ارفض المُخرجات غير الصالحة أو التي ليست ⁨PDF.⁩
الاحتياط المحلي	يعالج مُصيّر محلي اختياري عطل ⁨Worker.⁩	احقِن مصنع مُصيّر محلياً فقط عندما يدعمه المضيف.
أرشيف ⁨R2⁩	تخزّن R2ArchiveManager بايتات ⁨PDF⁩ وتنشئ عناوين ⁨URL⁩ موقَّعة.	أبقِ البيانات الوصفية غير حسّاسة ما لم تخزّنها عن قصد.

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

المسار	الغرض
app/Pdf/Cloudflare/*	غلاف التطبيق لـ CloudflareHtmlRenderer.
app/Pdf/Workers/*	كائنات نقل بيانات طلب ⁨Worker⁩ (⁨DTOs⁩) والسياسة الخاصة بنقطة النهاية.
app/Pdf/Archive/*	تنسيق أرشيف ⁨R2⁩ وقرارات الاحتفاظ.
app/Pdf/Fallback/*	تنفيذ LocalRendererFactoryInterface للاحتياط المسموح.
tests/Pdf/Cloudflare/*	اختبارات تعطّل ⁨Worker⁩، والرمز المميز غير الصالح، والحمولة، والأرشيف.

أبقِ رمز ⁨API⁩ المميز الخاص بـ ⁨PHP⁩ منفصلاً عن رمز ⁨Worker⁩ المميز. يصادِق ⁨PHP⁩ على ⁨Worker.⁩ وينبغي أن يصادِق ⁨Worker⁩ على الطلبات الواردة قبل أن يبدأ عمل المتصفح.

<?php

use NextPDF\Cloudflare\ApiProtection;
use NextPDF\Cloudflare\ApiProtectionConfig;
use NextPDF\Cloudflare\ApiKeyValidator;

$protection = new ApiProtection(
    new ApiProtectionConfig(maxRequestsPerMinute: 30),
    new ApiKeyValidator([$expectedApiKey]),
);

$result = $protection->checkRequest(
    clientId: $clientId,
    payloadSize: strlen($html),
    apiKey: $presentedApiKey,
);

if (!$result->allowed) {
    return new JsonResponse(['error' => $result->denialReason], 429, $result->toHeaders());
}

نمط المُصيّر

ابنِ المُصيّر باستخدام تبعيات توصيات معايير ⁨PHP⁩ (⁨PSR⁩) من إطار عملك، بما في ذلك ⁨PSR-18⁩ و⁨PSR-17⁩. أبقِ الاحتياط المحلي صريحاً حتى يتمكّن المشغّلون من معرفة متى يتوقّف النظام عن استخدام ⁨Worker.⁩

<?php

use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;

$renderer = new CloudflareHtmlRenderer(
    config: CloudflareRendererConfig::fromArray([
        'worker_url' => getenv('NEXTPDF_CLOUDFLARE_WORKER_URL'),
        'api_token' => getenv('NEXTPDF_CLOUDFLARE_API_TOKEN'),
        'render_timeout' => 30,
        'max_html_size' => 1_000_000,
        'fallback_to_local' => false,
    ]),
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
);

$rendered = $renderer->render($html, widthPt: 595.28);

نمط أرشيف ⁨R2⁩

لا تؤرشف إلا بعد نجاح التصيير وموافقة السياسة على النتيجة. تعامَل مع عناوين ⁨URL⁩ العامة وعناوين ⁨URL⁩ الموقَّعة بوصفها قرارين منفصلين.

<?php

use NextPDF\Cloudflare\R2ArchiveManager;

$upload = $archive->upload(
    pdfData: $rendered->pdfData,
    filename: 'invoice-1234.pdf',
    metadata: [
        'document_type' => 'invoice',
    ],
);

if ($upload->isValid()) {
    $temporaryUrl = $archive->generateSignedUrl($upload->key, 600);
}

لا تضع أسماء العملاء، أو عناوين البريد الإلكتروني، أو إجماليات الفواتير، أو المعرّفات المُنظَّمة في البيانات الوصفية للكائن ما لم تسمح سياسة الاحتفاظ والوصول لديك بذلك صراحةً.

نقاط التوسيع

نقطة التوسيع	استخدمها من أجل	القيد
LocalRendererFactoryInterface	الاحتياط المحلي عبر ⁨Artisan⁩ أو مُصيّر آخر.	يجب أن يُعيد كائناً يطبّق LocalRendererInterface.
ApiProtectionConfig	مفتاح ⁨API⁩، وحجم الحمولة، وسياسة تحديد المعدّل.	تنطبق الحدود في الذاكرة لكل عملية.
ApiKeyValidator	التحقق من المفتاح بأمان زمني ثابت ومساعِدات تدوير المفاتيح.	خزّن الأسرار خارج الشيفرة المصدرية.
R2ArchiveConfig	الدلو، والاعتمادات، وبادئة المسار، ونقطة النهاية، وحدود الحجم.	يجب ألا تُسجَّل الاعتمادات أبداً.
PinnedCurlTransport	فرض تثبيت بروتوكول الإنترنت (⁨IP⁩) ومعلومات المفتاح العام للموضوع (⁨SPKI⁩).	يتطلّب بيئة تشغيل تدعم ⁨cURL⁩ ومصنع استجابة.
CloudflareResponseParser	تحليل استجابة ⁨Worker.⁩	يرفض مُخرجات ⁨PDF⁩ غير الصالحة أو استجابات الخطأ.

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

1. ابنِ مسار تصيير محلياً أولاً.
2. أضِف تصيير ⁨Worker⁩ باستخدام مادة اختبار ⁨HTML⁩ صغيرة ومُمثِّلة.
3. فعّل حماية الطلب قبل كشف نقاط النهاية العامة.
4. أضِف رفع ⁨R2⁩ فقط بعد استقرار تدفقات التصيير والاستجابة.
5. اختبر مسارات تعطّل ⁨Worker⁩، والرمز المميز غير الصالح، والحمولة المفرطة الحجم، وحدّ المعدّل، وفشل ⁨R2.⁩
6. أضِف سجلات تميّز بين تصيير ⁨Worker⁩، وتصيير الاحتياط، ورفع الأرشيف، وإنشاء عنوان ⁨URL⁩ الموقَّع.

معالجة الأعطال

العطل	أين ينبغي معالجته	الاستجابة المُوصى بها
مفتاح ⁨API⁩ مفقود أو غير صالح	طبقة حماية ⁨API.⁩	ارفض الطلب قبل بدء عمل التصيير.
حمولة مفرطة الحجم	حماية ⁨API⁩ أو التحقق في المُصيّر.	أعِد فشل تحقق دون أي استدعاء لـ ⁨Worker.⁩
عنوان ⁨URL⁩ غير آمن لـ ⁨Worker⁩	سياسة أمان المُصيّر.	أفشِل الإعدادات أو الطلب قبل ⁨input/output⁩ الشبكة (⁨I/O⁩).
⁨Worker⁩ غير متاح	حدّ المُصيّر.	استخدم الاحتياط الصريح فقط عندما يكون مسموحاً به؛ وإلا فأفشِل بشكل ظاهر.
فشل رفع ⁨R2⁩	حدّ الأرشيف.	أعِد استجابة ⁨PDF⁩ إذا كان الأرشيف اختيارياً؛ وأفشِل العملية إذا كان الأرشيف مطلوباً بحسب السياسة.
فشل تدوير التثبيت	النشر والعمليات.	دوِّر باستخدام تثبيتات احتياطية وخطة تراجع.

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

الشأن	الافتراضي	متى تُلغى
الاحتياط	مُفعَّل افتراضياً بحسب الإعدادات.	عطّله عندما يخالف التصيير المحلي عزل النشر.
الحد الأقصى لحجم ⁨HTML⁩	5,000,000 بايت.	اخفضه لنقاط النهاية العامة.
مدة بقاء عنوان ⁨URL⁩ الموقَّع (⁨TTL⁩)	3600 ثانية.	اختصرها لملفات ⁨PDF⁩ الحسّاسة.
مجموعات التثبيت	فارغة.	أضِف التثبيتات فقط مع خطة تدوير وتثبيتات احتياطية.
اشتراط مفتاح ⁨API⁩	مُفعَّل افتراضياً بحسب إعدادات الحماية.	عطّله فقط للاستدعاءات الداخلية الخاصة المُصادَق عليها مسبقاً.

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

• تغطّي اختبارات المُصيّر ⁨HTML⁩ صالحة، و⁨HTML⁩ مفرطة الحجم، وعنوان ⁨URL⁩ غير صالح لـ ⁨Worker⁩، واستجابة خطأ من ⁨Worker.⁩
• تغطّي اختبارات حماية ⁨API⁩ مفتاحاً مفقوداً، ومفتاحاً غير صالح، وحمولة كبيرة جداً، وحدّ معدّل متجاوَزاً.
• تغطّي اختبارات ⁨R2⁩ الرفع الناجح، والرفع الكبير جداً، وحالة بروتوكول نقل النص الفائق (⁨HTTP⁩) الفاشلة، والدلو غير الصالح، وإنشاء عنوان ⁨URL⁩ الموقَّع.
• تتحقق اختبارات الاحتياط من أن مسار المُصيّر المحلي صريح وقابل للملاحظة.
• تغطّي اختبارات النقل عناوين ⁨IP⁩ المثبَّتة، وتثبيتات المفتاح العام، والمهلة، وإعادة التوجيه المُعطَّلة وفقاً للسياسة.
• تؤكّد اختبارات قابلية الملاحظة أحداث سجل متمايزة للتصيير، والاحتياط، والأرشيف، وإنشاء عنوان ⁨URL⁩ الموقَّع.