مرجع واجهة Cloudflare البرمجية

نظرة عامة

تصل حزمة NextPDF\Cloudflare العرضَ بالحافة. تحتفظ عملية ⁨PHP⁩ لديك بلغة ترميز النص التشعبي (⁨HTML⁩)، بينما يشغّل ⁨Cloudflare Worker⁩ المتصفح بلا واجهة. تعرض الحزمة أداة عرض ⁨HTML⁩ مدعومة بـ ⁨Worker⁩ (CloudflareHtmlRenderer) وكائنات القيمة التي تعيدها، وطبقة حماية طلبات لنقاط نهاية العرض (ApiProtection)، وخدمة أرشفة ⁨R2⁩ لملفات تنسيق المستندات المحمولة (⁨PDF⁩) المعروضة (R2ArchiveManager)، ومساعدات نقل مثبّتة لتعزيز أمان طبقة النقل (⁨TLS⁩) ونظام أسماء النطاقات (⁨DNS⁩). توجد الإعدادات في ثلاثة كائنات غير قابلة للتغيير (CloudflareRendererConfig، ApiProtectionConfig، R2ArchiveConfig).

للبدء، أنشئ CloudflareRendererConfig، واربطه بـ CloudflareHtmlRenderer، ثم استدعِ render(). يرسل هذا الاستدعاء ⁨HTML⁩ لديك إلى ⁨Worker⁩ ويعيد CloudflareRenderResult يحتوي على بايتات ملف ⁨PDF.⁩ تلتف الحماية والأرشفة والتثبيت حول هذا الاستدعاء.

المهام الشائعة

تغطّي هذه المقتطفات مسارات العمل التي ستستخدمها غالبًا. كل مقتطف مستقل، ومتحقّق منه مقابل src/Cloudflare/، ويقرأ الأسرار من البيئة.

اعرض سلسلة ⁨HTML⁩ كملف ⁨PDF⁩ على الحافة باستخدام الاستدعاء القياسي:

<?php

declare(strict_types=1);

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;

$httpFactory = new HttpFactory();

$renderer = new CloudflareHtmlRenderer(
    config: new CloudflareRendererConfig(
        workerUrl: 'https://pdf-renderer.example.workers.dev/render',
        apiToken: getenv('CF_PDF_TOKEN') ?: throw new RuntimeException('CF_PDF_TOKEN not set'),
    ),
    httpClient: new Client(),
    requestFactory: $httpFactory,
    streamFactory: $httpFactory,
    responseFactory: $httpFactory,
);

$result = $renderer->render('<h1>Hello from the edge</h1>', widthPt: 595.28);

if ($result->isValid()) {
    file_put_contents('output.pdf', $result->pdfData);
}

ما الذي يفعله: يرسل ⁨HTML⁩ إلى ⁨Worker⁩ عبر بروتوكول نقل النص التشعبي الآمن (⁨HTTPS⁩)، ويكتب بايتات ملف ⁨PDF⁩ بحجم ⁨A4⁩ المُعادة إلى القرص بعد أن يتأكد isValid() من وجود ملف ⁨PDF⁩ حقيقي.

أرشِف ملف ⁨PDF⁩ معروضًا في ⁨R2⁩ وأعِد رابطًا قصير الأجل:

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\R2ArchiveConfig;
use NextPDF\Cloudflare\R2ArchiveManager;

$archive = new R2ArchiveManager(
    config: R2ArchiveConfig::fromArray([
        'bucket_name'       => 'pdf-archive',
        'account_id'        => getenv('CF_ACCOUNT_ID') ?: '',
        'access_key_id'     => getenv('R2_ACCESS_KEY_ID') ?: '',
        'secret_access_key' => getenv('R2_SECRET_ACCESS_KEY') ?: '',
    ]),
    httpClient: $httpClient,         // PSR-18 ClientInterface
    requestFactory: $requestFactory, // PSR-17 RequestFactoryInterface
    streamFactory: $streamFactory,   // PSR-17 StreamFactoryInterface
);

$upload = $archive->upload($result->pdfData, 'invoice-1234.pdf');

$signedUrl = $upload->isValid()
    ? $archive->generateSignedUrl($upload->key, expiresInSeconds: 600)
    : null;

ما الذي يفعله: يرفع بايتات ⁨PDF⁩ إلى مفتاح ⁨R2⁩ مقسّم حسب التاريخ، ثم ينشئ عند النجاح محدّد موارد موحّدًا (⁨URL⁩) موقّعًا مسبقًا لمدة 10 دقائق للتنزيل المؤقت.

احمِ نقطة نهاية العرض قبل بدء عمل ⁨Worker⁩ المكلِف:

<?php

declare(strict_types=1);

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

$protection = new ApiProtection(
    config: new ApiProtectionConfig(maxRequestsPerMinute: 30),
    keyValidator: new ApiKeyValidator([getenv('RENDER_API_KEY') ?: '']),
);

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

if (!$decision->allowed) {
    // Reject with 429 and rate-limit headers before any render call.
    return [429, $decision->toHeaders(), $decision->denialReason];
}

ما الذي يفعله: يتحقق من مفتاح ⁨API⁩ وحجم الحِمل، ويفحص حد المعدل لكل عميل، ويعيد قرارًا واحدًا مع ترويسات الاستجابة التي يجب إرفاقها عند رفض الطلب.

أداة العرض

يغطّي هذا الجدول الواجهة الأساسية لأداة العرض. استخدمه عند إنشاء الإعدادات، أو بناء أداة العرض، أو تنفيذ استدعاءات العرض وفحوص التوفر.

الرمز	المعاملات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`new CloudflareRendererConfig(string $workerUrl, string $apiToken, int $renderTimeout = 30, string $defaultCss = '', int $maxHtmlSize = 5000000, ?string $r2FontBucket = null, bool $fallbackToLocal = true, array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	عنوان ⁨Worker⁩، ورمز الحامل، والمهلة، وأوراق الأنماط المتتالية (⁨CSS⁩)، وحد الحجم، وحاوية خطوط ⁨R2⁩ اختيارية، وراية الرجوع الاحتياطي، ومجموعات التثبيت.	الرجوع الاحتياطي المحلي مفعّل؛ والتثبيت معطّل عندما تكون مصفوفات التثبيت فارغة.	`CloudflareRendererConfig`	لا يُتوقع شيء.	احفَظ سرية رمز ⁨API⁩؛ وفضّل عناوين ⁨Worker⁩ التي تستخدم ⁨HTTPS.⁩
`CloudflareRendererConfig::fromArray(array $config)`	`worker_url`، `api_token`، `render_timeout`، `default_css`، `max_html_size`، `r2_font_bucket`، `fallback_to_local`، ومصفوفات التثبيت.	تستخدم المفاتيح الاختيارية المفقودة القيم الافتراضية للمنشئ.	`CloudflareRendererConfig`	لا يُتوقع شيء.	استخدمه لمصفوفات الإعدادات بأسلوب إطار العمل.
`CloudflareRendererConfig::isValid()`	لا شيء.	يتطلب عنوان ⁨Worker⁩ غير فارغ ورمز ⁨API.⁩	`bool`	لا يُتوقع شيء.	يؤدي الإعداد غير الصالح إلى الرجوع الاحتياطي أو إلى فشل أداة العرض.
`CloudflareRendererConfig::allPublicKeyPins()`	لا شيء.	يجمع تثبيتات المفتاح العام الأساسية والاحتياطية.	`list<string>`	لا يُتوقع شيء.	القائمة الفارغة تعطّل التثبيت.
`new CloudflareHtmlRenderer(CloudflareRendererConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?LocalRendererFactoryInterface $localRendererFactory = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	الإعدادات، واعتماديات بروتوكول نقل النص التشعبي (⁨HTTP⁩) وفق توصية معايير ⁨PHP⁩ (⁨PSR⁩)، ومسجّل اختياري، ومصنع رجوع احتياطي محلي اختياري، وسياسة ⁨HTML⁩ اختيارية، ومصنع استجابة اختياري.	يستخدم `DefaultHtmlSecurityPolicy` عند عدم توفير سياسة ⁨HTML.⁩	`CloudflareHtmlRenderer`	أخطاء ربط الحاوية.	يتيح مصنع الاستجابة نقل ⁨cURL⁩ المثبّت عند الحاجة.
`CloudflareHtmlRenderer::render(string $html, float $widthPt = 595.28, float $heightPt = 0, array $fontFiles = [])`	⁨HTML⁩، وعرض الصفحة، وارتفاع الصفحة، وملفات الخطوط في ⁨R2.⁩	عرض ⁨A4⁩، وارتفاع تلقائي، وبدون ملفات خطوط.	`CloudflareRenderResult`	`CloudflareNotAvailableException`، `CloudflareRenderException`، وإخفاقات التحقق.	يتحقق من حجم ⁨HTML⁩ وعنوان ⁨Worker⁩ قبل ⁨input/output⁩ (الإدخال/الإخراج).
`CloudflareHtmlRenderer::getHtmlSecurityPolicy()`	لا شيء.	يعيد سياسة طبقة التحليل المهيأة.	`HtmlSecurityPolicyInterface`	لا يُتوقع شيء.	استخدمها إلى جانب حماية نقطة النهاية والتحقق من عنوان ⁨Worker.⁩
`CloudflareHtmlRenderer::isAvailable()`	لا شيء.	يرسل طلب ⁨HEAD⁩ إلى ⁨Worker⁩ عندما تكون الإعدادات صالحة.	`bool`	يعيد `false` عند حدوث أخطاء.	استخدمه لفحوص الجاهزية، لا بصفته الحارس الوحيد في وقت التشغيل.

كائنات قيمة أداة العرض والأمان

استخدم هذا الجدول لكائنات قيمة الطلب والنتيجة (CloudflareRenderResult، CloudflareRenderPayload) وللفحوص الثابتة في طبقة النقل التي تتحقق من صحة ⁨HTML⁩ وعنوان ⁨Worker⁩ وتثبيتات ⁨DNS⁩ قبل الإدخال/الإخراج الشبكي.

الرمز	المعاملات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`new CloudflareRenderResult(string $pdfData, float $widthPt, float $heightPt, float $contentHeightPx = 0.0, string $renderLocation = '', float $renderTimeMs = 0.0)`	بايتات ⁨PDF⁩، والعرض، والارتفاع، وارتفاع المحتوى المقاس، وموقع الحافة، وزمن العرض.	تكون البيانات الوصفية فارغة عندما لا يرسلها ⁨Worker⁩.	`CloudflareRenderResult`	لا يُتوقع شيء.	يعيده `CloudflareResponseParser::parse()` عادةً.
`CloudflareRenderResult::isValid()`	لا شيء.	يتحقق من وجود بايتات ⁨PDF⁩ غير فارغة تبدأ برأس ⁨PDF.⁩	`bool`	لا يُتوقع شيء.	استخدمه قبل الأرشفة أو تمرير البايتات إلى طبقة أخرى.
`CloudflareRenderResult::size()`	لا شيء.	يحسب بايتات ⁨PDF⁩ المعروضة.	`int`	لا يُتوقع شيء.	أدخِله في منطق الحصص والتدقيق.
`new CloudflareRenderPayload(string $html, float $widthPt, float $heightPt = 0, string $defaultCss = '', ?string $r2FontBucket = null, array $fontFiles = [])`	⁨HTML⁩، والحجم، و⁨CSS⁩، وحاوية خطوط ⁨R2⁩ اختيارية، وقائمة ملفات الخطوط.	ارتفاع تلقائي، وبدون ⁨CSS⁩ افتراضي، وبدون حاوية خطوط ⁨R2⁩، وبدون ملفات خطوط.	`CloudflareRenderPayload`	لا يُتوقع شيء.	كائن قيمة حِمل الطلب.
`CloudflareRenderPayload::toJson()`	لا شيء.	يسلسل ⁨HTML⁩ والحجم و⁨CSS⁩ ومراجع الخطوط بصيغة ترميز كائنات جافا سكريبت (⁨JSON⁩) من أجل ⁨Worker.⁩	`string`	أخطاء ترميز ⁨JSON.⁩	واجهة منخفضة المستوى لحِمل الطلب.
`CloudflareResponseParser::parse(ResponseInterface $response, float $requestedWidthPt)`	استجابة ⁨Worker⁩ والعرض المطلوب.	يقبل استجابات ⁨PDF⁩ الثنائية واستجابات ⁨JSON⁩ المهيكلة.	`CloudflareRenderResult`	`CloudflareRenderException` لمخرجات ⁨Worker⁩ الفاشلة أو غير الصالحة.	المحلّل المركزي الذي تستخدمه أداة العرض.
`CloudflareSecurityPolicy::validate(string $html, int $maxSize)`	إدخال ⁨HTML⁩ وحد الحجم.	يطبّق سياسة إدخال ⁨HTML⁩ الخاصة بالحزمة.	`void`	استثناء تحقق.	أبقِ فحوص الإدخال غير الموثوق بها خارج حدود ⁨Worker.⁩
`CloudflareSecurityPolicy::validateWorkerUrl(string $url)`	عنوان ⁨Worker.⁩	يحلّل الوجهة ويتحقق من صحتها.	`array`	استثناء تحقق.	يحظر صيغ نقاط النهاية غير الآمنة قبل الإدخال/الإخراج الشبكي.
`CloudflareSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	المضيف وقائمة عناوين ⁨IP⁩ المثبّتة.	يتحقق من تثبيتات ⁨DNS⁩ المتوقعة.	`void`	استثناء تحقق عندما تكون التثبيتات قديمة أو غير صالحة.	استخدمه أثناء الفحوص التشغيلية للنشرات المثبّتة.

حماية ⁨API⁩

استخدم هذا الجدول عند حماية نقطة نهاية عرض: التحقق من مفتاح ⁨API⁩، وفحوص حجم الحِمل وحد المعدل، وكائنات النتيجة والترويسات الناتجة عنها.

الرمز	المعاملات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`new ApiProtection(ApiProtectionConfig $config, ?ApiKeyValidator $keyValidator = null, ?Closure $clock = null)`	إعدادات الحماية، وأداة تحقق مفاتيح اختيارية، وساعة اختيارية.	يستخدم وقت النظام عند عدم توفير ساعة.	`ApiProtection`	لا يُتوقع شيء.	احقِن ساعة حتمية في الاختبارات.
`ApiProtection::checkRequest(string $clientId, int $payloadSize, string $apiKey = '')`	معرّف العميل، وحجم الحِمل، ومفتاح ⁨API⁩ اختياري.	يُسمح بمفتاح ⁨API⁩ فارغ فقط عندما لا يتطلب الإعداد مفاتيح.	`ApiProtectionResult`	لا يُتوقع شيء.	يفحص مفتاح ⁨API⁩ والحجم، ثم يطبّق حدود المعدل.
`ApiProtection::getRateLimit(string $clientId)`	معرّف العميل.	لا يسجّل طلبًا.	`RateLimitResult`	لا يُتوقع شيء.	استخدمه لإضافة ترويسات حد المعدل.
`new ApiKeyValidator(array $validKeys = [])`	قائمة بالمفاتيح النصية الصالحة.	القائمة الفارغة ترفض جميع المفاتيح.	`ApiKeyValidator`	لا يُتوقع شيء.	خزّن الأسرار خارج الشيفرة وعبّئها عبر الإعداد.
`ApiKeyValidator::validate(string $key)`	المفتاح الخام.	يقارنه بالمفاتيح النصية المهيأة باستخدام منطق آمن من حيث التوقيت.	`bool`	لا يُتوقع شيء.	المعامل حساس؛ لا تسجّل المفاتيح الخام.
`ApiKeyValidator::addKey(string $key)`	المفتاح الخام.	يضيف مفتاحًا مجزّأً إلى نسخة جديدة من أداة التحقق.	`self`	لا يُتوقع شيء.	تعامَل مع النسخة المُعادة بصفتها أداة التحقق المحدّثة.
`ApiKeyValidator::revokeKey(string $key)`	المفتاح الخام.	يزيل التجزئة المطابقة من نسخة جديدة من أداة التحقق.	`self`	لا يُتوقع شيء.	تعامَل مع النسخة المُعادة بصفتها أداة التحقق المحدّثة.
`ApiKeyValidator::hashKey(string $key)`	المفتاح الخام.	ينتج التمثيل المجزّأ المخزّن.	`string`	لا يُتوقع شيء.	لا تكشف التجزئات في السجلات أو استجابات العميل.
`ApiKeyValidator::validateHashed(string $key, array $hashedKeys)`	المفتاح الخام والتجزئات المرشّحة.	يقارن بالتجزئات المزوّدة في زمن ثابت.	`bool`	لا يُتوقع شيء.	مساعد منخفض المستوى لمخازن المفاتيح المخصّصة.
`new ApiProtectionConfig(int $maxRequestsPerMinute = 60, int $maxRequestsPerHour = 1000, int $maxPayloadSizeBytes = 10485760, array $allowedOrigins = [], bool $requireApiKey = true, string $apiKeyHeader = 'X-Api-Key', int $rateLimitWindowSeconds = 60)`	حدود الطلبات، وحد الحِمل، والأصول المسموح بها، ومتطلب مفتاح ⁨API⁩، واسم الترويسة، وطول النافذة.	60/⁨minute⁩، 1000/⁨hour⁩، وحِمل 10 ⁨MiB⁩، ومفتاح ⁨API⁩ مطلوب.	`ApiProtectionConfig`	لا يُتوقع شيء.	أنشئه مباشرةً في الاختبارات أو عبّئه باستخدام `fromArray()`.
`ApiProtectionConfig::fromArray(array $data)`	`max_requests_per_minute`، `max_requests_per_hour`، `max_payload_size_bytes`، `allowed_origins`، `require_api_key`، `api_key_header`، `rate_limit_window_seconds`.	تستخدم المفاتيح المفقودة القيم الافتراضية للمنشئ.	`ApiProtectionConfig`	لا يُتوقع شيء.	استخدمه لتعبئة إعداد إطار العمل.
`ApiProtectionConfig::isValid()`	لا شيء.	يتطلب حدودًا موجبة وقيم حجم ونافذة متّسقة.	`bool`	لا يُتوقع شيء.	تحقّق قبل كشف نقطة نهاية.
`new ApiProtectionResult(bool $allowed, string $denialReason = '', ?RateLimitResult $rateLimit = null)`	القرار، وسبب الرفض، ونتيجة حد المعدل الاختيارية.	سبب رفض فارغ وبدون نتيجة حد المعدل.	`ApiProtectionResult`	لا يُتوقع شيء.	يُعاد بواسطة `ApiProtection::checkRequest()`.
`ApiProtectionResult::toHeaders()`	لا شيء.	يصدر ترويسات حد المعدل عند وجود بيانات المعدل.	`array<string, string>`	لا يُتوقع شيء.	أرفِقها باستجابات ⁨Worker⁩ أو إطار العمل.
`new RateLimitResult(bool $allowed, int $remainingRequests, int $retryAfterSeconds, string $clientId)`	القرار، والعدد المتبقي، وتأخير إعادة المحاولة، ومعرّف العميل (⁨ID⁩).	لا توجد قيم افتراضية.	`RateLimitResult`	لا يُتوقع شيء.	نتيجة غير قابلة للتغيير لفحص منفرد.
`RateLimitResult::toHeaders()`	لا شيء.	يصدر ترويسات الحد المتبقي وإعادة التعيين.	`array<string, string>`	لا يُتوقع شيء.	استخدمه للمراقبة وتراجع العميل.
`new RateLimitEntry(string $clientId, int $requestCount = 0, int $windowStart = 0, int $hourlyCount = 0, int $hourlyWindowStart = 0)`	معرّف العميل وعدّادات قابلة للتغيير.	تبدأ العدّادات من الصفر.	`RateLimitEntry`	لا يُتوقع شيء.	كائن تتبّع داخل الذاكرة.
`RateLimitEntry::increment()`	لا شيء.	يزيد العدّاد في الذاكرة لـ ⁨client/window.⁩	`void`	لا يُتوقع شيء.	مساعد منخفض المستوى يستخدمه `ApiProtection`.
`RateLimitEntry::isExpired(int $windowSeconds)`	طول النافذة بالثواني.	يقارن بالوقت الحالي.	`bool`	لا يُتوقع شيء.	مساعد انتهاء الصلاحية في وقت التشغيل.
`RateLimitEntry::isExpiredAt(int $now, int $windowSeconds)`	قيمة الساعة وطول النافذة.	يقارن بقيمة الساعة المزوّدة.	`bool`	لا يُتوقع شيء.	مساعد اختبار حتمي.
`RateLimitEntry::reset()`	لا شيء.	يعيد تعيين العدد ووقت بدء النافذة.	`void`	لا يُتوقع شيء.	يُستخدم عند بدء نافذة جديدة.

أرشيف ⁨R2⁩

استخدم هذا الجدول عند تخزين ملفات ⁨PDF⁩ المعروضة في ⁨Cloudflare R2⁩: خدمة الأرشفة، وإعداداتها، وأنواع مفتاح الكائن الخاصة بها، ونتيجة الرفع التي ينبغي فحصها قبل كشف عنوان ⁨URL.⁩

الرمز	المعاملات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`new R2ArchiveManager(R2ArchiveConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory)`	إعداد ⁨R2⁩ و ⁨HTTP⁩ وفق ⁨PSR⁩، ⁨factories/client.⁩	لا يوجد استدعاء شبكي أثناء الإنشاء.	`R2ArchiveManager`	أخطاء ربط الحاوية.	خدمة الأرشفة الرئيسية.
`R2ArchiveManager::upload(string $pdfData, string $filename, array $metadata = [])`	بايتات ⁨PDF⁩ الخام، واسم الملف الأصلي، والبيانات الوصفية النصية.	بيانات وصفية فارغة؛ ومفتاح مقسّم حسب التاريخ.	`R2UploadResult`	يعيد نتيجة غير ناجحة عند إخفاق الإعدادات أو الحجم أو ⁨HTTP⁩ أو النقل.	لا يطرح استثناءً عند إخفاق الرفع المعتاد.
`R2ArchiveManager::generateSignedUrl(string $key, int $expiresInSeconds = 3600)`	مفتاح الكائن ومدة بقاء عنوان ⁨URL⁩ (⁨TTL⁩).	عنوان ⁨URL⁩ موقّع لمدة ساعة واحدة.	`string`	أخطاء توقيع ناتجة عن إعدادات غير صالحة.	استخدم قيم ⁨TTL⁩ قصيرة لملفات ⁨PDF⁩ الحساسة.
`R2ArchiveManager::buildObjectKey(string $filename)`	اسم الملف الأصلي.	يستخدم بادئة المسار المهيأة والتاريخ الحالي.	`R2ObjectKey`	لا يُتوقع شيء.	استخدمه لتقسيم الأرشيف بطريقة متوقّعة.
`R2ArchiveManager::createPutRequest(R2ObjectKey $key, string $data, array $metadata = [])`	مفتاح الكائن، والبايتات الخام، والبيانات الوصفية.	يوقّع طلب ⁨PUT.⁩	`RequestInterface`	أخطاء إنشاء الطلب.	واجهة منخفضة المستوى لطبقات نقل مخصّصة.
`new R2ArchiveConfig(string $bucketName, string $accountId, string $accessKeyId, string $secretAccessKey, string $endpoint = '', string $pathPrefix = 'pdfs/', int $maxFileSizeBytes = 104857600)`	الحاوية، ومعرّف الحساب، وبيانات الاعتماد، وتجاوز نقطة النهاية، وبادئة المفتاح، والحجم الأقصى للكائن.	نقطة نهاية مشتقّة، وبادئة `pdfs/`، وحد أقصى لحجم الكائن قدره 100 ⁨MiB.⁩	`R2ArchiveConfig`	`InvalidArgumentException` لأسماء الحاويات غير الصالحة.	تعامَل مع بيانات الاعتماد بصفتها إعدادات تحمل أسرارًا.
`R2ArchiveConfig::fromArray(array $data)`	معرّف الحساب، والحاوية، وبيانات الاعتماد، وبادئة المسار، وتجاوز نقطة النهاية، والحجم الأقصى.	تستخدم القيم المفقودة القيم الافتراضية للمنشئ.	`R2ArchiveConfig`	اسم حاوية غير صالح عند تقديمه.	استخدمه لتعبئة إعداد التطبيق.
`R2ArchiveConfig::isValid()`	لا شيء.	يتطلب حسابًا وحاويةً ومفتاح وصول ومفتاحًا سريًا غير فارغة.	`bool`	لا يُتوقع شيء.	تجعل الإعدادات غير الصالحة عمليات الرفع تفشل مع نتائج مهيكلة.
`R2ArchiveConfig::getEndpoint()`	لا شيء.	يستخدم نقطة نهاية صريحة أو يشتق نقطة نهاية ⁨Cloudflare R2⁩ من معرّف الحساب.	`string`	لا يُتوقع شيء.	يُستخدم لإنشاء الطلبات الموقّعة.
`new R2ObjectKey(string $key, string $bucket)`	مفتاح الكائن الكامل والحاوية.	لا يجري أي تطبيع.	`R2ObjectKey`	لا يُتوقع شيء.	يُنشأ عادةً بواسطة `R2ObjectKey::generate()`.
`R2ObjectKey::generate(string $prefix, string $filename, ?DateTimeInterface $date = null)`	البادئة، واسم الملف الأصلي، والتاريخ الاختياري.	مفتاح كائن مقسّم حسب التاريخ ومنقّح.	`R2ObjectKey`	لا يُتوقع شيء.	احقِن التاريخ في الاختبارات للحصول على مفاتيح حتمية.
`R2ObjectKey::fullPath()`	لا شيء.	يدمج مسار التقسيم واسم ملف الكائن.	`string`	لا يُتوقع شيء.	خزّن هذه القيمة بصفتها مفتاح الكائن.
`new R2UploadResult(bool $success, string $key, string $etag = '', int $size = 0, string $error = '')`	راية النجاح، ومفتاح الكائن، ووسم الكيان (⁨ETag⁩)، وحجم البايتات، ورسالة الخطأ.	⁨ETag⁩ فارغ، وحجم صفري، وخطأ فارغ.	`R2UploadResult`	لا يُتوقع شيء.	يعيده `R2ArchiveManager::upload()`.
`R2UploadResult::isValid()`	لا شيء.	يكون صالحًا عند نجاح الرفع ووجود كل من المفتاح و ⁨ETag.⁩	`bool`	لا يُتوقع شيء.	تحقّق قبل كشف عناوين ⁨URL.⁩
`R2UploadResult::publicUrl(string $customDomain = '')`	نطاق عام مخصّص اختياري.	يعيد مفتاح الكائن المجرّد عند عدم توفير نطاق مخصّص.	`string`	لا يُتوقع شيء.	تجنّب عناوين ⁨URL⁩ العامة للمستندات الحساسة ما لم تسمح السياسة بذلك.

مساعدات النقل

استخدم هذا الجدول للربط منخفض المستوى فقط: تثبيت بروتوكول الإنترنت (⁨IP⁩) و ⁨SubjectPublicKeyInfo⁩ (⁨SPKI⁩) على مستوى ⁨cURL⁩، إضافةً إلى عقود أداة العرض المحلية المستخدمة مسارًا للرجوع الاحتياطي عندما يتعذّر الوصول إلى ⁨Worker.⁩

الرمز	المعاملات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	مصانع ⁨PSR-17⁩، وعناوين ⁨IP⁩ المثبّتة، والمفاتيح العامة المثبّتة، والمهلة.	لا توجد تثبيتات، والمهلة 30 ثانية.	`PinnedCurlTransport`	لا يُتوقع شيء.	استخدمه فقط عند الحاجة إلى التثبيت على مستوى ⁨cURL.⁩
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	طلب وفق ⁨PSR-7.⁩	يرسل عبر ⁨cURL⁩ بالمهلة المهيأة وضوابط التثبيت.	`ResponseInterface`	استثناءات النقل وفق ⁨PSR-18.⁩	استخدمه فقط عندما يتعذّر على عملاء ⁨HTTP⁩ في إطار العمل فرض سياسة التثبيت نفسها.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	الطلب، والمضيف الهدف، والمنفذ الهدف.	ينشئ مصفوفة خيارات ⁨cURL⁩ التي يستخدمها `sendRequest()`.	`array`	أخطاء في الطلب غير الصالح أو إعدادات التثبيت.	خطّاف منخفض المستوى للاختبار والتشخيص.
`LocalRendererInterface::render(string $html, array $options = [])`	⁨HTML⁩ وخيارات أداة العرض.	عقد فقط؛ يحدد التنفيذ القيم الافتراضية.	`string`	أخطاء عرض خاصة بالتنفيذ.	يُستخدم رجوعًا احتياطيًا محليًا عندما يكون عرض ⁨Worker⁩ غير متاح.
`LocalRendererFactoryInterface::create()`	لا شيء.	ينشئ تنفيذًا لأداة عرض محلية.	`LocalRendererInterface`	أخطاء المصنع أو الاعتمادية.	يُبقي إنشاء أداة العرض الاحتياطية خارج `CloudflareHtmlRenderer`.

ملاحظات التطوير

تعامَل مع عنوان ⁨Worker⁩ بصفته حدًا شبكيًا. تحقّق من الوجهة والحجم والمصادقة قبل العرض.
استخدم نتائج حماية ⁨API⁩ بصفتها مخرجات سياسة، لا مسار تحكم قائمًا على الاستثناءات.
تعيد عمليات رفع ⁨R2⁩ نتائج نجاح أو خطأ مهيكلة؛ تعامَل مع كلا المسارين.