HTML: HTML+CSS'ten PDF'ye işleyen alt sistem

Bir bakışta

HTML alt sistemi, HyperText Markup Language (HTML) ve Cascading Style Sheets (CSS) içeriğini tek ileri geçişte Portable Document Format (PDF) içerik akışlarına dönüştürür. Bu, motorun en büyük ve en yüksek risk taşıyan alt sistemidir; src/Html/ altında 324 dosya bulunur.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

HTML alt sistemi, HTML+CSS’i PDF’ye dönüştüren tek geçişli, akış tabanlı bir işleyicidir. Genel API yüzeyi tek bir yöntemden oluşur: Document::writeHtml(). İçeride HtmlParser girdiyi belirteçlere ayırır, stilleri çözer, yerleşimi hesaplar ve belge ağacı tutmadan tek ileri geçişte PDF operatörleri üretir.

Kapsamı açık tutun. Bu alt sistem, belgeyi bellekte tutan bir işleyici değildir. Bir öğe grafiği tutmaz, zaten yazılmış içeriği yeniden yerleştirmez ve ayrıştırma başladıktan sonra girdinin değişmesine izin vermez. Sabit belirtim sürümlerine bağlı, özenle seçilmiş bir CSS alt kümesini uygular. Bu davranışı iki Architecture Decision Record (ADR) yönetir. ADR-001 tek geçişli akış modelini ve üst sınırlarını tanımlar. ADR-010 dört katmanlı sözleşmeyi (CSS ayrıştırma, stil durumu, yerleşim, boyama) ve buna ek olarak sayfalanmış medya ile ölçüm yardımcılarını tanımlar.

HtmlParser, modül bildiriminde kritik risk olarak derecelendirilir. Beş dosya, belgelenmiş tehlikeli bölge açıklamaları taşır: HtmlParser düzenleyicisi (akışlı belirteçleyici, 1000+ satır kod (LOC)), HtmlStyleState (yığın kalıtımı modeline sahip 100+ CSS özellik alanı), HtmlBlockHandler (stil durumuna bağlı blok dağıtımı), FlexLayoutEngine (tam flex ölçümü ve yerleşimi) ve TableParser (sayfa sonları boyunca colspan/rowspan sayfalama). Buradaki değişiklikleri plan modunda yürütülecek iş olarak ele alın.

Bu sayfayı giriş noktası olarak kullanın. Aşamaların sırası için pipeline sayfasına, art arda uygulama ve belirginlik için css-resolver sayfasına, katman sınırları için layer-contracts-adr010 sayfasına ve ağaç tutmayan model ile üst sınırlar için streaming-constraints-adr001 sayfasına bakın.

Sağdan sola ve çift yönlü metin

writeHtml(), sağdan sola (RTL) içeriği işler. CSS direction: rtl özelliğini gövdeye, bir tabloya veya herhangi bir öğeye ayarlayın. Motor, görsel sırayı tipografi katmanının çift yönlü motoru aracılığıyla Unicode Çift Yönlü Algoritması (UAX #9) ile çözümler — BidiEngine ayrıntıları için Tipografi sayfasına bakın. Karışık Latin, Arapça ve sayısal içerik doğru sıralanır ve Arapça’dan sonra gelen bir sayı, basamaklarını soldan sağa korur.

Arapça ayrıca bağlamsal şekillendirme alır: motor, her harfin başlangıç, ortadaki, son veya yalın biçimini seçer ve Lam-Alef bağını uygular. Şekillendirme, karakter haritası Arabic Presentation Forms-B bloğunu kapsayan kayıtlı bir yazı tipi gerektirir; standart-14 yazı tipleri de dâhil olmak üzere yalnızca Latin içeren bir yüz Arapça çizemez. Tablolarda, her hücre kendi başına yeniden sıralanır ve şekillendirilir ve direction: rtl altında başlangıç (sağ) kenarına hizalanır. RTL; Arapça, İbranice, Farsça ve Urduca için geçerlidir; İbranice yeniden sıralanır ancak şekillendirilmez.

Yönü CSS direction özelliğiyle ayarlayın — HTML dir özniteliği buna eşlenmez. Tablo dışı blok ve satır içi metnin yatay hizalaması ve text-align: justify henüz uygulanmıyor. Çalıştırılabilir bir Arapça fatura ve geçerli sınırların tam listesi için Sağdan sola Arapça HTML işleme sayfasına bakın.

API yüzeyi

Simge	Konum	Rol
`Document::writeHtml(string $html): static`	`src/Core/Concerns/HasTextOutput.php`	Genel giriş noktası. HTML’yi geçerli imleç konumunda işler.
`Document::createStandalone(): self`	`src/Core/Document.php`	Bağımsız bir belge oluşturur.
`HtmlParser::parse(string $html): HtmlRenderResult`	`src/Html/HtmlParser.php`	Dahili düzenleyici.
`HtmlRenderResult`	`src/Html/HtmlRenderResult.php`	Değişmez sonuç: akış, bitiş imleci ve kullanılan yazı tipleri.
`DefaultHtmlSecurityPolicy`	`src/Html/DefaultHtmlSecurityPolicy.php`	Varsayılan etiket, öznitelik, CSS ve Uniform Resource Locator (URL) ilkesi.
`HtmlSecurityPolicyInterface`	`src/Contracts/HtmlSecurityPolicyInterface.php`	Özel ilkeler için ilke sözleşmesi.

Kod örneği — hızlı başlangıç

Kaynak: examples/08-html-basic.php.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('HTML Basic');
$doc->addPage();
$doc->writeHtml('<h1 style="color:#1E3A8A;">HTML Rendering</h1><p>Direct to PDF.</p>');
$doc->save(__DIR__ . '/output/08-html-basic.pdf');

Kod örneği — üretim

Bu örnek, examples/09-html-table.php dosyasını temel alır ve gömülü bir stil bloğu içeren bir tablo raporunu gösterir.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Exception\HtmlParsingException;

function renderInventory(string $rowsHtml, string $out): void
{
    $doc = Document::createStandalone();
    $doc->setTitle('Inventory');
    $doc->addPage();

    $html = '<style>table { width: 100%; } '
          . 'th { background-color: #1E3A8A; color: #FFFFFF; }</style>'
          . '<table border="1" cellpadding="5">' . $rowsHtml . '</table>';

    try {
        $doc->writeHtml($html);
    } catch (HtmlParsingException $e) {
        // Input cap, element cap (50,000), or nesting cap (100). Do not retry.
        throw $e;
    }

    $doc->save($out);
}

Sınır durumlar ve dikkat edilecek noktalar

Özenle seçilmiş CSS alt kümesi. Destek, her modül için sabitlenmiştir. Bir özelliğe güvenmeden önce CSS destek matrisini denetleyin.
Kesin üst sınırlar özel durum fırlatır. 10 MB girdi, 50,000 öğe ve 100 iç içe geçme düzeyi üst sınırlarından herhangi biri aşılırsa HtmlParsingException fırlatılır. akış kısıtlamaları sayfasına bakın.
Yeniden yerleşim yoktur. İşleyici, çıktıyı belge sırasına göre bir kez yazar; sonradan gelen stiller daha önceki çıktıyı değiştiremez.
:has() geçit denetimine tabidir; deneysel css.has özelliğinin arkasında yer alır.
Kritik riskli alt sistem. Beş dosya tehlikeli bölge olarak işaretlenmiştir. src/Html/ altındaki değişiklikler için plan modunu kullanın.

Tek geçişli akış kısıtlamaları (ADR-001)

İşleyici hiçbir belge ağacı tutmaz ve tek ileri geçiş çalıştırır. Öğe, iç içe geçme ve girdi üst sınırları kesin sınırlardır. Ayrıntıların tamamı ve çalışma güvenliği sözleşmesi için akış kısıtlamaları (ADR-001) sayfasına bakın.

Katman sözleşmeleri (ADR-010)

CSS ayrıştırma, stil durumu, yerleşim ve boyama tek yönlü sözleşmelerle dört katmana ayrılmıştır; buna ek olarak sayfalanmış medya ve ölçüm yardımcıları yer alır. Ayrıntıların tamamı için katman sözleşmeleri (ADR-010) sayfasına bakın.

Büyük belgeler için bellek bütçesi

Stil durumu ve imleç belleği, O(öğe sayısı) değil O(iç içe geçme derinliği) ölçeğindedir. Sayfa başına performance_budget değerinde peak_mb: 64 belirtilmiştir. 50,000 öğelik üst sınır kesin bir tavandır; daha büyük girdileri birden çok writeHtml() çağrısına bölün. Ayrıntılar için akış kısıtlamaları sayfasına bakın.

Performans

Dolaşma maliyeti, O(belirteç sayısı) ölçeğindedir. Tablo sütun boyutlandırması, tablo başına sınırlı bir satır taraması ekler. İsteğe bağlı :has() ön taraması, sınırlı bir belirteç listesi geçişi ekler. HTML işleme hattı performans karşılaştırması, %5’lik bir gerileme geçidi uygular (birleşik çalışma, pull request (PR) #564). Sayfa başına performance_budget (wall_ms: 1500, peak_mb: 64) operasyonel üst sınırdır.

Güvenlik notları

DefaultHtmlSecurityPolicy, ayrıştırıcıdan bağımsız olarak etiketler, öznitelikler, CSS özellikleri ve URL şemaları için bir izin listesi uygular; ayrıca 10 MB girdi tavanını ve 100 düzeylik iç içe geçme tavanını zorunlu kılar. CSS özellik izin listesi, güvenlik tavanıdır. Çalışma zamanındaki destek tablosu, ayrı bir yetenek tavanıdır. Daha katı bir ilke sağlamak için HtmlSecurityPolicyInterface arabirimini uygulayın. DefaultExternalResourcePolicy dış kaynak getirmeyi ayrı olarak yönetir.

Bir bağlantının href değeri ve bir görüntünün src değeri için URL izin listesi, ters eğik çizgi köklü (\…) ve Universal Naming Convention (UNC) (\\host\share) yolları da reddeder; bu, mevcut protokol-göreli (//) reddine ve yalnızca http(s) ya da göreli değerlere izin veren listeye ek olarak uygulanır. Ters eğik çizgiler denetimden önce düz eğik çizgilere normalleştirilir; böylece Windows mutlak yolu kullanan bir yerel dosya ekleme işlemi veya bir Server Message Block (SMB) paylaşımı getirme işlemi, “şema yok, dolayısıyla göreli” dalından geçemez. Her iki yol da bir Uniform Resource Identifier (URI) şeması taşımaz.

CSS destek matrisi alıntısı (yalnızca doğrulanmış satırlar)

Bu sayfa, özellik bazında desteği yeniden belirtmez. CSS destek matrisi, hangi modüllerin doğrulanmış, hangilerinin iddia edilmiş olduğu dâhil olmak üzere, her World Wide Web Consortium (W3C) modülü için doğrulama durumunun tek yetkili kaynağıdır.

Uygunluk

Alt sistem, sabit belirtim sürümlerinde özenle seçilmiş bir CSS alt kümesini uygular. Art arda uygulamaya ilişkin davranışsal belirtim eşlemeleri, css-resolver sayfasında madde ve parça tanımlayıcılarıyla belgelenmiştir. Modül bazında uygunluk durumu CSS destek matrisinde yer alır.

Ticari bağlam

Kurumsal yetenek. Premium, aynı tek geçişli hat üzerinde CSS kapsamını (gelişmiş baskı ve ek modüller) genişletir. Mimari, üst sınırlar ve katman sözleşmeleri sürümler arasında aynı kalır. CSS destek matrisine bakın.