NextPDF Artisan genel bakışı

Bir bakışta

NextPDF Artisan, NextPDF için Chrome köprüsüdür. Bir Hypertext Markup Language (HTML) parçasını Chrome DevTools Protocol (CDP) üzerinden başsız bir Chrome işlemine gönderir, printToPDF çıktısını yakalar ve sonucu hedef Portable Document Format (PDF) belgesine Form XObject olarak gömer. Gömülü metin seçilebilir ve aranabilir kalır.

Kavramsal genel bakış

Artisan paketi (nextpdf/artisan), açık kaynaklı NextPDF motorunu, yerleşimi Chrome’a devreden bir işleyiciyle genişletir. NextPDF’in yerel HTML işlem hattı, geniş bir Cascading Style Sheets (CSS) alt kümesini zaten kapsar. CSS flexbox ve grid, data Uniform Resource Identifier (URI) kaynaklarından yüklenen özel web yazı tipleri ve karmaşık seçiciler dahil olmak üzere Chrome düzeyinde yerleşim gerektiren belgelerde Artisan köprüsünü kullanın; köprü, rasterleştirilmiş bir ekran görüntüsü yerine vektör metni üretmeye devam eder.

Köprü, küçük ve tek amaçlı bileşenlerden oluşan bir işlem hattı olarak çalışır. ChromeHtmlRenderer tek bir işlemeyi düzenler. ChromeSecurityPolicy girdiyi doğrular ve güvenlik açısından kilitlenmiş bir HTML belgesine sarar. BrowserPool Chrome işlem yaşam döngüsünü yönetir. ViewportCalculator PDF noktalarını CSS piksellerine eşler. NextPDF\Parser okuyucusu Chrome çıktısını ayrıştırır ve PageImporter bunu Form XObject’e dönüştürür. Her bileşen final olarak işaretlidir, yapıcı üzerinden enjekte edilir ve PHPStan seviye 10’da tiplenmiştir.

Köprünün dış bağımlılıkları vardır. chrome-php/chrome kitaplığına (^1.15) ve PHP işleminin erişebileceği bir Chrome ya da Chromium ikili dosyasına gereksinim duyar. Bunların hiçbiri pakete dahil değildir. Kitaplık yoksa, köprü sessizce başarısız olmak yerine ChromeNotAvailableException oluşturur; /integrations/artisan/troubleshooting/ sayfasındaki /integrations/artisan/failure-modes/ bölümüne bakın.

İşleyici, girdi ChromeSecurityPolicy::validate() denetiminden geçene kadar Chrome’a asla içerik göndermez. Chrome’un aldığı belge, Content-Security-Policy başlığı aracılığıyla katı bir Content Security Policy (CSP) ve katmanlı savunma sağlayan CDP ağ engellemesiyle her zaman sarmalanır. Köprü, güvenilmeyebilecek HTML içeriğini işlediğinden, çevreleme ve yalıtım modeli burada özetlenmek yerine /integrations/artisan/security-and-operations/ sayfasında belgelenir.

Bu sayfa, paketin dağıtıldığı haliyle davranışını açıklar; src/Artisan/ ve tests/Unit/Artisan/ kümesiyle doğrulanmıştır. Bu, etkileşimli bir Chrome tarayıcısıyla piksel piksel eşdeğerlik iddiası değildir: animasyonlar son karelerinde yakalanır, yerleşim JavaScript’e dayanmaz ve yalnızca ilk Chrome sayfası içe aktarılır.

Mimari

Diagram

Bileşen sorumlulukları

Bileşen	Sorumluluk	Kaynak
ChromeHtmlRenderer	Tek bir işlemeyi düzenler; döndürdüğü değer: ChromeRenderResult	src/Artisan/ChromeHtmlRenderer.php
ChromeRendererConfig	Değişmez yapılandırma değer nesnesi	src/Artisan/ChromeRendererConfig.php
ChromeSecurityPolicy	Girdi doğrulama + güvenli HTML zarfı	src/Artisan/ChromeSecurityPolicy.php
BrowserPool	Chrome işlem yaşam döngüsü ve yeniden başlatma ilkesi	src/Artisan/BrowserPool.php
ViewportCalculator	72 pt/inch ↔ 96 px/inch dönüşümü	src/Artisan/ViewportCalculator.php
ChromeRenderResult	Tiplenmiş işleme çıktısı (ChromeRenderResultInterface)	src/Artisan/ChromeRenderResult.php
PageImporter	Ayrıştırılmış Chrome sayfası → ImportedFormXObject	src/Artisan/PageImporter.php
EInvoiceServiceFactory	Premium e-fatura sözleşmeleri için kapsayıcısız fabrika	src/Artisan/EInvoiceServiceFactory.php

Sınır durumları ve püf noktaları

• Sürüm kökeni. Yayımlanan Composer yapıtı v0.1.0 olarak etiketlenmiştir. Kaynak docblock’ları @since 1.7.0 (Chrome köprüsü) ve @since 1.1.0 (e-fatura fabrikası) işaretlerini taşır; bunların ikisi de yeniden adlandırma öncesindeki nextpdf/core sürüm hattından devralınmıştır; paket, nextpdf/artisan olarak 2.0.0 CHANGELOG girdisinde yeniden adlandırılmıştır. Composer etiketini kurulum için yetkili sürüm, @since işaretlerini ise motor sürümü geçmişi olarak değerlendirin.
• Yalnızca ilk sayfa. PageImporter::import() varsayılan olarak sayfa dizini için 0 değerini kullanır. İkinci bir Chrome sayfasına taşan içerik, /integrations/artisan/production-usage/ sayfasında anlatıldığı gibi açık bir yükseklik belirtmediğiniz sürece kırpılır.
• Bağımlılık enjeksiyonu (DI) kapsayıcısı yok. Artisan kapsayıcısızdır. EInvoiceServiceFactory, bir hizmet kapsayıcısı bulunmayan ortamlarda hizmet örnekleri oluşturmak için tutarlı bir yol sunar; bkz. /integrations/artisan/boot-and-discovery/.

Performans

Her işleme çağrısı, Chrome sayfa yükleme ve printToPDF maliyetini bir kez üstlenir. BrowserPool, Chrome işlemini işlemeler arasında çalışır durumda tutar ve bellek büyümesini sınırlamak için her 100 işlemede bir yeniden başlatır. Big-O davranışını köprünün kendisi değil, Chrome’un yerleşim işi belirler. Bu sayfanın referans akışına ait ölçülmüş bütçe için, frontmatter içindeki performance_budget alanına ve /integrations/artisan/production-usage/ sayfasına bakın.

Güvenlik notları

Köprü, güvenilmeyebilecek HTML içeriğini Chrome içinde işler. Girdi, Chrome’a ulaşmadan önce boyut ve içerik açısından doğrulanır. Sarmalanan belge default-src 'none' içerir. CDP düzeyindeki bir engelleme, her alt kaynak isteğini durdurur. Chrome sandbox bayrağının açıkça belirtilen sınırları dahil olmak üzere, tam çevreleme ve yalıtım modeli /integrations/artisan/security-and-operations/ sayfasındadır. Bu bölümü eksiksiz güvenlik duruşu olarak değerlendirmeyin.

Ticari bağlam

Açık kaynaklı köprü, HTML içeriğini PDF olarak işler. Premium katmanlar, işlenen belgenin üzerine uyumlu e-fatura gömme (Pro) ve doğrulama (Enterprise) ekler. Bu katmanlar yüklenmediğinde EInvoiceServiceFactory null döndürür; böylece açık kaynak yolu bunlar olmadan da tümüyle işlevsel kalır.

Ayrıca bkz.

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/quickstart/
• /integrations/artisan/chrome-renderer-setup/
• /integrations/artisan/security-and-operations/
• /integrations/artisan/production-usage/