Hızlı başlangıç — ilk edge işlemeniz

Bir bakışta

Bu sayfada bir Köprü Metni İşaretleme Dili (HTML) dizesini bir Taşınabilir Belge Biçimi (PDF) dosyasına dönüştürürsünüz. Her çağrı bir metoda karşılık gelir; her metodun davranışı tests/Unit/Cloudflare/CloudflareHtmlRendererTest.php içinde doğrulanır.

Ön koşullar

• İşleme sözleşmesini Güvenli Köprü Metni Aktarım Protokolü (HTTPS) üzerinden sunan bir Worker uç noktası.
• Worker’ın kabul ettiği bir bearer belirteci.
• Kullanıma hazır bir PHP Standartları Önerisi 18 (PSR-18) istemcisi ve PHP Standartları Önerisi 17 (PSR-17) fabrikaları (bkz. /integrations/cloudflare/install/).

Worker sözleşmesinin CloudflareResponseParser üzerinden gözlemlenen davranışı şöyledir: başarılı olduğunda Köprü Metni Aktarım Protokolü (HTTP) 200 döndürür. Yanıt, ya Content-Type: application/pdf (ham PDF baytları) ya da Content-Type: application/json (base64 kodlu bir pdf alanıyla) içerir. 200 dışındaki her durum ya da %PDF işaretleyicisiyle başlamayan her gövde, başarısızlık olarak değerlendirilir.

Adım 1 — Yapılandırmayı oluşturma

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Cloudflare\CloudflareRendererConfig;

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

Belirteç ortamdan alınır ve hiçbir zaman koda gömülmez. workerUrl HTTPS kullanmalıdır. Bir http:// URL’si geçirirseniz, köprü herhangi bir istek göndermeden önce değeri Worker URL must use HTTPS ile reddeder.

Adım 2 — İşleyiciyi oluşturma

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

$httpFactory = new HttpFactory();

$renderer = new CloudflareHtmlRenderer(
    config:          $config,
    httpClient:      new Client(),     // PSR-18 ClientInterface
    requestFactory:  $httpFactory,     // PSR-17 RequestFactoryInterface
    streamFactory:   $httpFactory,     // PSR-17 StreamFactoryInterface
    logger:          null,             // optional PSR-3 LoggerInterface
    responseFactory: $httpFactory,     // PSR-17; enables the pinned transport
);

Kurucu dört bağımsız değişken gerektirir: yapılandırma, PSR-18 istemcisi, istek fabrikası ve akış fabrikası. Dört bağımsız değişken daha isteğe bağlıdır: günlükleyici, yerel işleyici fabrikası, açık bir HTML güvenlik politikası ve yanıt fabrikası. Yanıt fabrikası sağlandığında, çözümlenmiş bir İnternet Protokolü (IP) kümesi ya da bir Konu Açık Anahtar Bilgisi (SPKI) sabitleme kümesi mevcutsa sabitlenmiş cURL aktarımı etkinleşir (bkz. /integrations/cloudflare/security-and-operations/).

Adım 3 — İşleme ve yazma

use NextPDF\Cloudflare\Exception\CloudflareNotAvailableException;
use NextPDF\Cloudflare\Exception\CloudflareRenderException;

try {
    $result = $renderer->render('<h1>Hello from the edge</h1>');

    if (!$result->isValid()) {
        throw new RuntimeException('Worker did not return a valid PDF');
    }

    file_put_contents('output.pdf', $result->pdfData);
    printf("Wrote %d bytes from edge %s in %.1f ms\n",
        $result->size(),
        $result->renderLocation !== '' ? $result->renderLocation : 'unknown',
        $result->renderTimeMs,
    );
} catch (CloudflareRenderException $e) {
    // Worker answered but the render failed (HTTP error or malformed body).
    fwrite(STDERR, 'Render failed: ' . $e->getMessage() . PHP_EOL);
    exit(1);
} catch (CloudflareNotAvailableException $e) {
    // Worker unreachable and no usable fallback.
    fwrite(STDERR, 'Edge unavailable: ' . $e->getMessage() . PHP_EOL);
    exit(2);
}

render() varsayılan olarak A4 genişliğini (595.28 PDF noktası) ve otomatik algılanan yüksekliği (heightPt: 0) kullanır. İki istisna türü özellikle ayrı tutulmuştur. CloudflareRenderException Worker tarafındaki bir başarısızlığı gösterir ve bir geri dönüşle yeniden denenmez. CloudflareNotAvailableException, edge’e ulaşılamadığı ve kullanılabilir bir yerel geri dönüş bulunmadığı anlamına gelir.

Adım 4 — Sonucu inceleme

CloudflareRenderResult bir final readonly sınıftır. Aşağıdaki alanlar ikili yolda yanıt üst bilgilerinden ya da JSON yolunda JavaScript Nesne Gösterimi (JSON) alanlarından doldurulur.

Üye	Kaynak
pdfData	Ham PDF baytları
widthPt	İstenen genişlik
heightPt	X-Pdf-Height-Pt üst bilgisi / JSON heightPt; yoksa ya da pozitif değilse varsayılan olarak 841.89 (A4 yüksekliği)
contentHeightPx	X-Content-Height-Px / JSON contentHeightPx
renderLocation	Şu kaynaktan türetilir: CF-Ray üst bilgisi son eki (ikili yol) ya da JSON renderLocation
renderTimeMs	X-Render-Time-Ms / JSON renderTimeMs
size()	strlen($pdfData)
isValid()	true: baytlar şununla başladığında: %PDF

İsteğe bağlı — özel kâğıt boyutu, yazı tipleri, CSS

$result = $renderer->render(
    html:     '<div style="font-family: NotoSansCJK;">繁體中文文件</div>',
    widthPt:  595.28,
    heightPt: 841.89,           // explicit A4; 0 lets the Worker auto-detect
    fontFiles: ['NotoSansCJKtc-Regular.ttf'],
);

fontFiles yalnızca yapılandırmada r2FontBucket değeri ayarlandığında anlamlıdır. Yük, Worker’ın bunları yükleyebilmesi için kova adını ve istenen yazı tipi dosyası yollarını birlikte taşır.

İsteğe bağlı — kullanılabilirlik yoklaması

if ($renderer->isAvailable()) {
    $result = $renderer->render($html);
}

isAvailable(), Worker URL’sine kimlik doğrulamalı bir HTTP HEAD gönderir. true döndürür, durum 500 değerinin altında olduğunda. Yapılandırma geçersiz olduğunda ya da istek başarısız olduğunda, istisna fırlatmadan false döndürür. Bunu garanti olarak değil, ipucu olarak değerlendirin. Worker sonraki POST isteğinde yine de başarısız olabilir.

Ayrıca bakınız

• /integrations/cloudflare/production-usage/ — geri dönüş bağlantıları, telemetri ve R2 arşivleme.
• /integrations/cloudflare/troubleshooting/ — her başarısızlık, kendi istisnasına ve iletisine eşlenmiştir.
• /integrations/cloudflare/configuration/ — tam alan başvurusu.