Artisan geliştirici kılavuzu

Bir bakışta

Artisan paketinin birbirine bağlı iki sorumluluğu vardır: Köprü Metni İşaretleme Dili (HTML) belgesini Chrome aracılığıyla işlemek ve ortaya çıkan Taşınabilir Belge Biçimi (PDF) sayfasını bir NextPDF belgesine içe aktarmak. Sorun giderirken Chrome, ayrıştırıcı ve içe aktarıcı sınırlarını ayrı tutun.

İşleyici tümleştirmeleri, uzun ömürlü çalışanlar, ayrıştırıcı tanılaması veya nextpdf/artisan için testler yazarken bu kılavuzu kullanın.

Mimari sınır

Katman	Sahibi	Sorumluluk	Buraya koymayın
Uygulama	Uygulama	HTML üretimini yetkilendirin ve işleyici yapılandırmasını seçin.	Tarayıcı süreci yönetimi.
HTML ilkesi	Uygulama ve paket	Güvensiz veya aşırı büyük HTML belgesini işlenmeden önce reddedin.	Kiracı yetkilendirmesi veya iş kararları.
Chrome işleyicisi	`nextpdf/artisan`	HTML belgesini Chrome tarafından üretilen bağımsız bir PDF olarak işleyin.	Genel PDF onarımı veya rastgele PDF düzenleme.
Ayrıştırıcı/içe aktarıcı	`nextpdf/artisan`	İşlenen PDF’yi ayrıştırın ve bir sayfayı form XObject olarak içe aktarın.	Tam PDF uygunluğu doğrulaması.
Çekirdek motor	`nextpdf/nextpdf`	İçe aktarılan form nesnelerini yerleştirin ve son belgeyi yazın.	Chrome DevTools Protocol (CDP) yaşam döngüsü.

Çalışma zamanı yaşam döngüsü

Aşama	Davranış	Geliştirici eylemi
Yapılandırma oluşturma	`ChromeRendererConfig` ikili dosyayı, zaman aşımını, Basamaklı Stil Sayfaları (CSS) davranışını, giriş boyutunu ve korumalı alan davranışını tanımlar.	Sabit kodlanmış çalışma zamanı tahminleri yerine ortama özgü yapılandırma kullanın.
İşleyici oluşturma	`ChromeHtmlRenderer` bir `BrowserPool` nesnesini barındırır.	İşleyiciyi bir çalışan içinde yeniden kullanın, ardından kapatma sırasında kapatın.
HTML doğrulaması	Güvenlik ilkesi boyutu denetler ve belgeyi varsayılan CSS ile sarmalar.	Bu aşamadan önce çağıranın yetkilendirmesini doğrulayın.
Chrome yazdırma	CDP bağımsız bir PDF oluşturur.	İncelenmiş bir ilke izin vermediği sürece dış kaynakları engellenmiş tutun.
PDF ayrıştırma	`PdfReader::parse()` xref verilerini, sayfaları, nesneleri, kaynakları ve düzeltmeleri okur.	Hedefli tanılama yapmıyorsanız ayrıştırıcı hatalarını işleme hatası olarak değerlendirin.
Sayfa içe aktarma	`PageImporter::import()` sayfa içeriğini, ortam kutusunu, kaynakları ve gömülü nesneleri ayıklar.	İş akışı bilinçli olarak başka bir sayfa seçmediği sürece `0` numaralı sayfayı içe aktarın.

Önerilen uygulama yapısı

Yol	Amaç
`app/Pdf/Renderers/*`	Şu sınıf etrafındaki uygulama sarmalayıcısı: `ChromeHtmlRenderer`.
`app/Pdf/Templates/*`	HTML şablonu işleme ve veri aktarım nesnesinden (DTO) görünüme eşleme.
`app/Pdf/Policies/*`	HTML boyutu, kaynak ve kiracı işleme ilkesi.
`tests/Pdf/Renderer/*`	Küçük HTML eşlemelerini kullanan işleyici duman testleri.
`tests/Pdf/Parser/*`	İçe aktarılan Chrome çıktısı için ayrıştırıcı eşlemeleri.

Şablon işlemeyi tarayıcıda işlemeden ayrı tutun. İşleyiciye nihai HTML belgesini ve bilinen bir sayfa genişliğini geçirin.

<?php

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(
    renderTimeout: 30,
    maxHtmlSize: 1_000_000,
));

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

$reader = new PdfReader($result->getPdfData());
$reader->parse();

$form = (new PageImporter())->import($reader);

İşleyici düzeni

Her çalışan süreci veya her istek kapsamı için bir işleyici oluşturun. Yinelenen Chrome başlatma maliyetinden kaçınmak için işleyiciyi yeniden kullanın. Çalışan kapatılırken süreç sızıntılarını önlemek için işleyiciyi açıkça kapatın.

<?php

final class InvoiceChromeRenderer
{
    public function __construct(
        private readonly ChromeHtmlRenderer $renderer,
    ) {}

    public function renderInvoice(string $html): string
    {
        return $this->renderer
            ->render($html, widthPt: 595.28)
            ->getPdfData();
    }

    public function close(): void
    {
        $this->renderer->close();
    }
}

Ayrıştırıcı tanılama düzeni

Chrome çıktısı içe aktarılamadığında ayrıştırıcı uygulama programlama arabirimlerini (API’ler) kullanın. Tanılamayı salt okunur tutun ve başarılı bir içe aktarmadan sonra ayrıştırıcı durumunu değiştirmekten kaçının.

Tanılama sorusu	Kullanılacak API	Beklenen sinyal
Dosya ayrıştırılabiliyor mu?	`PdfReader::parse()`	Geçersiz PDF yapısında bir özel durum oluşturur.
Sayfa `0` var mı?	`PdfReader::getPage(0)`	Bir `PdfObject` döndürür.
İçerik var mı?	`PdfReader::getPageContentStream($page)`	Boş olmayan içerik akışı.
Kaynaklar mevcut mu?	`PdfReader::getPageResources($page)`	Kaynak sözlüğü dizisi.
Artımlı düzeltmeler var mı?	`PdfReader::getRevisionCount()`	Birden büyük bir sayı.
Hangi nesne başarısız oldu?	`PdfTokenizer::getOffset()` ve ayrıştırıcı özel durum bağlamı.	Eşlemeyi küçültmek için bayt uzaklığı.

Genişletme noktaları

Genişletme noktası	Şunun için kullanın	Kısıtlama
`ChromeRendererConfig::fromArray()`	Çerçeve yapılandırması eşlemesi.	Bilinmeyen veya yanlış türde isteğe bağlı değerler varsayılanlara geri döner.
`HtmlSecurityPolicyInterface`	Ayrıştırma katmanı için HTML ilkesi.	Aktarım, süreç veya yetkilendirme denetimlerinin yerini almaz.
`LoggerInterface`	İşleme ve tarayıcı tanılaması.	HTML içeriğini varsayılan olarak günlüğe kaydetmeyin.
`BrowserPool`	Uzun ömürlü Chrome sürecinin yeniden kullanımı.	Çalışan kapatılırken kapatılmalıdır.
`PageImporter`	Ayrıştırılmış bir dış sayfayı gömme.	Okuyucu önce ayrıştırılmalıdır.
Ayrıştırıcı sınıfları	Tanılama ve içe aktarılan Chrome çıktısı.	Genel amaçlı bir PDF onarım araç takımı değildir.

Geliştirme iş akışı

HTML parçasını en küçük işleme testinde yeniden üretin.
Doğrulayın: maxHtmlSize, varsayılan CSS ve Chrome ikili dosya yolu.
Nokta cinsinden sabit bir genişlikle işleyin.
Döndürülen PDF baytlarını PdfReader::parse() ile ayrıştırın.
İş akışı bilinçli olarak başka bir sayfa seçmediği sürece 0 numaralı sayfayı içe aktarın.
Her hatayı yeniden üreten en küçük HTML için eşleme testleri ekleyin.
İşleyiciyi çalışan kapatma kancalarında kapatın.

Hata işleme

Hata	Nerede işlenmelidir	Önerilen yanıt
Chrome ikili dosyası eksik	Dağıtım denetimi ve işleyici oluşturma yolu.	İşleme trafiğini kabul etmeden önce hazırlık denetimini başarısız sayın.
Aşırı büyük HTML	HTML ilkesi.	Chrome’u başlatmadan önce reddedin.
Tarayıcı zaman aşımı	İşleyici sınırı.	İşlemeyi başarısız sayın; şablon adını, boyutunu, genişliğini ve zaman aşımını kaydedin.
Ayrıştırıcı hatası	İçe aktarma sınırı.	İlke izin verdiğinde hata ayıklama için küçük, temizlenmiş bir eşleme depolayın.
Tarayıcı süreci sızıntısı	Çalışan yaşam döngüsü.	Kapatma sırasında kapatın ve denetimli işleme sayılarından sonra yeniden başlatın.

Güvenli varsayılanlar

Konu	Varsayılan	Ne zaman geçersiz kılınmalı
İşleme zaman aşımı	`30` saniye.	Yalnızca ölçülmüş, sınırlı belgeler için artırın.
Maksimum HTML boyutu	`5,000,000` bayt.	Genel uç noktalar için düşürün.
Korumalı alan	Etkin.	Yalnızca kapsayıcı kısıtlamaları gerektirdiğinde ve ana makine yalıtılmışken devre dışı bırakın.
Yükseklik	Şu koşulda otomatik: `heightPt <= 0`.	Katı yerleşim sözleşmeleri için sabit yükseklik kullanın.
Dış kaynaklar	İşleyici ilkesi tarafından engellendi.	Yalnızca incelenmiş bir kaynak ilkesi aracılığıyla izin verin.

Test denetim listesi

İşleme testleri temsili HTML ve CSS’yi kapsar.
Güvenlik testleri aşırı büyük HTML belgesini ve engellenen kaynak girişimlerini kapsar.
İçe aktarma testleri, döndürülen form nesnesinin içeriğe, ortam kutusuna ve kaynaklara sahip olduğunu doğrular.
Ayrıştırıcı testleri çapraz başvuru (xref) tablosu, xref akışı, nesne akışı ve hatalı biçimlendirilmiş eşleme durumlarını kapsar.
Çalışan testleri close() çağırır ve hiçbir tarayıcı sürecinin kalmadığını doğrular.
Performans testleri işleme süresini şablona ve içerik boyutuna göre kaydeder.