HTML işleme hattı

Bir bakışta

Siz writeHtml() işlevini çağırdığınızda, HyperText Markup Language (HTML) üzerinde tek bir ileri geçiş çalıştırılır: girdi token’lara ayrılır, @page ve stiller çözümlenir, içerik yerleştirilir ve Portable Document Format (PDF) işleçleri yazılır. Aşamalar arasında bir öğe ağacı saklanmaz.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

HTML işleme hattı, HTML+CSS içeriğini, yani HTML ve Cascading Style Sheets (CSS) bileşimini, tek bir ileri geçişte PDF içerik akışı işleçlerine dönüştürür. Saklanan bir belge ağacı oluşturulmaz. Aşağıdaki aşamalar, HtmlParser::parse() işlevinin main dalındaki davranışını yansıtır.

Aşama 1 — Temizleme ve normalleştirme. HtmlParser::parse() 10 MB’tan büyük girdileri reddeder, denetim karakterlerini ayıklar ve satır sonlarını normalleştirir: hem CRLF hem de tek başına CR, LF’ye dönüştürülür; bu davranış, kaynaktaki HTML satır sonu normalleştirmesiyle eşleşir. Ardından her örnek alanı sıfırlanır; böylece önceki bir çağrıdan kalan durum sonraki çağrıya taşınamaz.

Aşama 2 — @page ve stil bloklarını ayıkla. Ayrıştırıcı önce <style> bloklarını ayıklar, ardından bulunan @page kurallarını sayfa geometrisini yeniden yapılandırmak için uygular. Bu işlem herhangi bir token işlenmeden önce yapılır, çünkü sayfa boyutu sonraki her yerleşim kararını etkiler.

Aşama 3 — Token’lara ayır. HtmlTokenizer::cleanHtml() <pre> içeriğini korurken boşlukları normalleştirir. Ardından tokenize() düz bir list<HtmlToken> üretir. Bu, bir düğüm grafiği değil, bir token listesidir. İşleme hattı, yalnızca boşluktan oluşan metin token’larını hemen atar. HtmlChildScanner::scan() düz liste üzerinde dizin haritaları (alt öğe sayıları, etiket sayıları, boşluk durumu) oluşturur; böylece yapısal seçiciler için ağaç gerekmez.

Aşama 4 — İsteğe bağlı :has() ön taraması. css.has deneysel özelliğini etkinleştirdiğinizde, ilişkisel seçiciyi çözümlemek için CssResolver::resolveHasSelectors() token listesi üzerinde sınırlı bir ön tarama çalıştırır. Belgelenmiş ve sınırlandırılmış bu adım, tek geçiş kuralının istisnasıdır.

Aşama 5 — Token’ları işle (stil, yerleşim, boyama). HtmlParser::processTokens() token listesi üzerinde bir kez dolaşır. Her öğe için art arda gelmeyi (cascade) çözümler (Katman 1 uygulayıcıları HtmlStyleState yazar), geometriyi hesaplar (Katman 3 yerleşim) ve PDF işleçlerini yayar (Katman 4 boyama). Stil kalıtımı, push ve pop işlemlerinin uygulandığı bir HtmlStyleState yığını kullanır. İmleç (x, y, kenar boşlukları, akış uzaklığı), işleyiciler arasında HtmlBlockCursor anlık görüntüleri aracılığıyla taşınır.

Aşama 6 — Sonucu döndür. parse(), yayılan içerik akışını, bitiş imleci konumunu ve kullanılan yazı tipi anahtarlarını içeren değişmez bir HtmlRenderResult döndürür. Çağıran taraf (writeHtml()) imleci sayfa koordinat çerçevesine geri taşır.

Aşama 5 içindeki dört katmanlı ayrım için katman sözleşmeleri sayfasına bakın. Ağaç saklanmaması özelliği ve sınırları için akış kısıtlamaları sayfasına bakın.

API yüzeyi

Sembol	Konum	Aşama
`Document::writeHtml(string $html): static`	`src/Core/Concerns/HasTextOutput.php`	Genel giriş noktası
`HtmlParser::parse(string $html): HtmlRenderResult`	`src/Html/HtmlParser.php`	Tüm aşamaları düzenler
`HtmlTokenizer::cleanHtml()` / `tokenize()`	`src/Html/HtmlTokenizer.php`	Aşama 3
`HtmlChildScanner::scan()`	`src/Html/HtmlChildScanner.php`	Aşama 3 dizin haritaları
`CssResolver::resolveHasSelectors()`	`src/Html/CssResolver.php`	Aşama 4 (kapılı)
`HtmlRenderResult` (`stream`, `endX`, `endY`, `usedFontKeys`)	`src/Html/HtmlRenderResult.php`	Aşama 6

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

Kaynak: examples/08-html-basic.php dosyasıdır.

<?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>One pass.</p>');
$doc->save(__DIR__ . '/output/08-html-basic.pdf');

Kod örneği — Üretim

Gömülü bir <style> bloğu içeren biçimlendirilmiş bir rapor oluşturun. İşleme hattı, herhangi bir token işlenmeden önce stil bloğunu ayıklar ve uygular.

<?php

declare(strict_types=1);

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

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

function renderInvoice(string $bodyHtml, string $out): void
{
    $doc = Document::createStandalone();
    $doc->setTitle('Invoice');
    $doc->addPage();

    $html = '<style>@page { margin: 20mm; } '
          . 'h1 { color: #1E3A8A; } '
          . 'table { width: 100%; }</style>'
          . $bodyHtml;

    try {
        $doc->writeHtml($html);
    } catch (HtmlParsingException $e) {
        // Sanitize/cap failures surface here. Do not retry.
        throw $e;
    }

    $doc->save($out);
}

Uç durumlar ve dikkat edilecek noktalar

@page token’lardan önce okunur. İçerikten sonra gelen bir @page kuralı yine de uygulanır, çünkü stil ayıklama token’lara ayırmadan önce gerçekleşir. Sayfa geometrisi Aşama 5’ten önce sabitlenir.
<pre> boşlukları korunur. cleanHtml() <pre> içeriğini korur; işleme hattı diğer yerlerdeki boşlukları daraltır.
:has() kapılıdır. css.has deneysel özelliğini etkinleştirmezseniz, Aşama 4 çalışmaz ve :has() seçicileri eşleşmez.
Tek bir akış arabelleği. İşleme hattı tek bir dize arabelleğine yazar. Zaten yazılmış olan içeriği asla taşımaz. Yeniden yerleşim yapılmaz.
Üst sınırlar geçiş ortasında uygulanır. Öğe ve iç içe geçme üst sınırları öncesinde değil, Aşama 5 sırasında özel durum fırlatır. Bir belge işlemin ortasında başarısız olabilir.

Performans

İşleme hattı O(token sayısı) karmaşıklığında ilerler. Tablo sütun boyutlandırması, tablo başına sınırlı bir satır taraması ekler (Aşama 5, TableParser). Etkinleştirildiğinde, :has() ön taraması token listesi üzerinde sınırlı bir geçiş ekler (Aşama 4). Stil yığınının bellek kullanımı O(öğe sayısı) değil, O(iç içe geçme derinliği) düzeyindedir; bkz. akış kısıtlamaları. HTML işleme hattı performans karşılaştırması, %5’lik bir eşikle gerilemelere karşı koruma sağlar (birleştirilmiş çalışma, PR #564). Sayfa başına performance_budget (wall_ms: 1500, peak_mb: 64) işletimsel üst sınırdır.

Güvenlik notları

Aşama 1 ilk güvenlik sınırıdır: 10 MB’lık girdi üst sınırı, denetim karakterlerinin ayıklanması ve satır sonu normalleştirmesinin tümü token’lara ayırmadan önce çalışır. Aşama 5 sırasında DefaultHtmlSecurityPolicy, izin verilen etiketleri, öznitelikleri, CSS özelliklerini ve URL şemalarını kapılar. HTML modülü güvenlik modeli sayfasına bakın.

Uyumluluk

Satır sonu normalleştirmesi, HTML standardının satır sonu işleyişini izler: CRLF ve tek başına CR, LF’ye dönüştürülür. Özellik bazında CSS uyumluluğu CSS destek matrisi sayfasında, art arda gelme (cascade) davranışı ise css-resolver sayfasında belgelenmiştir. Bu sayfa, özellik bazında desteği yeniden belirtmez.

Ticari bağlam

Kurumsal yetenek. Premium, aynı işleme hattında CSS kapsamını genişletir. Altı aşamalı dizi, sürümler arasında değişmez. CSS destek matrisi sayfasına bakın.