HTML'i PDF sayfası olarak işleme

Bir bakışta

Hypertext Markup Language (HTML) ve Cascading Style Sheets (CSS) içeren bir parçayı Portable Document Format (PDF) sayfa içeriği olarak işlemek için writeHtml() yöntemini kullanın. İşaretlemeyi yönteme iletin; NextPDF biçimlendirilmiş bir sayfa oluşturur. Bu kodun eksiksiz ve çalıştırılabilir sürümü examples/08-html-basic.php dosyasındadır. Aşağıdaki adımları izleyin veya örneği doğrudan kopyalayın.

NextPDF, HTML’inizi bir kez okur ve sonucu doğrudan sayfaya aktarır. Bu, tek geçişli bir akış işlem hattıdır. Bu tarifi kullanmak için bu modeli anlamanız gerekmez. Yine de bunu aklınızda bulundurun, çünkü bu sayfanın ilerleyen bölümlerindeki birkaç kuralı açıklar.

Kurulum

composer require nextpdf/core:^3

Bu komut, nextpdf/core paketini kurar. Bu sayfadaki örnekler PHP 8.4 üzerinde çalışır ve desteklenen çalışma zamanı sürümü >=8.4 <9.0 aralığıdır.

Kavramsal genel bakış

writeHtml(), bir HTML dizesi alır ve onu geçerli imleç konumundan başlayarak geçerli sayfaya çizer. Dahili olarak NextPDF, HTML’inizi bir kez tarar ve belirteçlere ayırır (HtmlTokenizer). Ardından bu listeyi soldan sağa doğru dolaşır (HtmlParser). Her öğe için, içerik akışı işleçleri adı verilen karşılık gelen PDF çizim yönergelerini bir arabelleğe yazar. Motor, çağrılar arasında bellekte hiçbir zaman bir öğe ağacı oluşturmaz veya saklamaz. Bu bilinçli tasarım tercihi, ADR-001’de kayıtlı tek geçişli akış modelidir.

Desteklenen her blok öğesi bir yerleşim kutusuna, her metin dizisi de bir metin gösterme işlecine dönüşür. Satır içi style özniteliklerinden ve bir <style> bloğundan gelen stiller, birden fazla stil uygulandığında hangisinin geçerli olacağını belirleyen CSS basamaklama kurallarıyla çözümlenir. Metin kaydırma, hizalama ve aralıklandırma, kaynak metnin biçimlendirilmiş ve satıra kaydırılmış metne nasıl dönüştürüleceğini tanımlayan CSS Text modelini izler (W3C CSS Text Level 3).

Bir yazı tipi seçmezseniz, gövde metni varsayılan bir yazı tipi yüzü kullanır. Bu varsayılan, ISO 32000-2’de adı geçen 14 standart yazı tipinden biri olan standart bir Type 1 yazı tipidir. Varsayılan yalnızca kendi yazı tipinizi kaydedip seçtiğinizde veya bir uygunluk profili NextPDF’in bir ikame gömmesini gerektirdiğinde değişir.

Beklentiyi en baştan netleştirin: NextPDF, HTML ve CSS’in bir alt kümesini destekler, ikisinin tamamını değil. Bu tarif, desteklenen alt kümeyi kapsar. Tam HTML veya tam CSS desteği iddiasında bulunmaz. Her modülün tam ve doğrulanmış durumu için CSS destek matrisine bakın.

API yüzeyi

Yöntem imzası writeHtml(string $html): static şeklindedir. Bu yöntem NextPDF\Contracts\PdfDocumentInterface arabiriminde bildirilir ve NextPDF\Core\Concerns\HasTextOutput içinde uygulanır. Yöntem çıktıyı geçerli sayfaya işler ve henüz bir sayfa yoksa sizin için bir tane oluşturur. Yöntemin tam PHPDoc tablosu kaynak koddan üretilir.

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

<?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>HTML Rendering in NextPDF</h1><p>Rendered with <strong>writeHtml()</strong>.</p>');

$doc->save(__DIR__ . '/out.pdf');

Kod örneği — Üretim

Bu eksiksiz, kendi kendine yeten örnek, test koşum aygıtının çalıştırdığı örnektir. examples/08-html-basic.php dosyasını yansıtır. Bir çıktı yolunu sabit kodlamak yerine, koşum aygıtının sağladığı yola yazar. Bu sayede yeniden üretilebilirlik koşum aygıtı komut dosyasını iki kez çalıştırıp sonuçları karşılaştırabilir.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('HTML Basic');
$doc->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">HTML Rendering in NextPDF</h1>

<p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.
This is the recommended approach for <em>mixed formatting</em>.</p>

<h2>Supported elements</h2>

<ul>
    <li>Headings (h1-h6)</li>
    <li>Paragraphs with <strong>bold</strong> and <em>italic</em></li>
    <li>Ordered and unordered lists</li>
    <li>Tables with borders and alignment</li>
    <li>Inline styles (color, font-size, margin)</li>
</ul>

<h2>Ordered list</h2>

<ol>
    <li>Create a Document instance</li>
    <li>Add pages and content</li>
    <li>Call save() or output()</li>
</ol>
HTML;

$doc->writeHtml($html);

// The harness sets NEXTPDF_COOKBOOK_OUTPUT and runs this script twice.
// Honour it: do not hard-code a path, do not echo the PDF to STDOUT.
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/render-html-to-pdf.pdf');

echo "Wrote render-html-to-pdf.pdf\n";

Beklenen STDOUT:

Wrote render-html-to-pdf.pdf

Uç durumlar ve tuzaklar

İmleç ilerlemesi. writeHtml(), imleci işlenen içeriğin sonuna taşır. Sonraki bir cell() veya ikinci bir writeHtml() çağrısı, sayfanın üstünden değil, oradan devam eder.
Henüz sayfa yok. Hiçbir sayfa yoksa, writeHtml() işlemeden önce bir tane ekler. Belirli bir sayfa boyutu ayarlamanız gerektiğinde önce addPage() çağrısı yapın.
Öğe ve iç içe geçme üst sınırları. Akış motoru, 50,000 öğelik bir üst sınır ve 100 düzeylik bir iç içe geçme üst sınırı uygular (ADR-001). Her iki üst sınırı da aşan bir belge, sessizce kırpılmak yerine reddedilir.
Desteklenmeyen işaretleme. Desteklenen alt kümenin dışındaki öğeler ve özellikler yoksayılır veya yedek davranışa düşer; hata oluşturmazlar. Bir özelliğe güvenmeden önce CSS destek matrisine göre kapsamı denetleyin.
Dış kaynaklar. Uzaktaki görseller ve stil sayfaları dış kaynak ilkesini izler; varsayılan ilke rastgele uzak URL’leri getirmez.

Performans

Belirteçlere ayırma ve işleme, girdiniz üzerinde tek geçişte gerçekleşir; bu nedenle maliyet belirteç sayısıyla O(n) olarak doğrusal artar. Bu tarifin varsayılan bütçesi wall_ms: 1500, peak_mb: 96 şeklindedir. Motor çıktıyı akışla aktardığından ve bellekte hiçbir Document Object Model (DOM) tutmadığından, zirve bellek kullanımı tüm belge boyutundan ziyade içerik akışı arabelleğine ve etkin stil yığınına bağlıdır.

CSS destek matrisi alıntısı (yalnızca Verified satırları)

Bu alıntı, yalnızca Verified olarak derecelendirilen satırları içerir; bu satırlar doğruluk denetiminden geçmiş CSS destek matrisinden alınmıştır. “Verified”, bir src/Html/ uygulamasının ve yapısal profil altında belirlenimci biçimde geçen kapsamlı, ayrı bir fikstür paketinin var olduğu anlamına gelir.

W3C modülü	Düzey	Durum	Kanıt
CSS Flexible Box Layout (`css_flexbox_1`)	1	Verified	`src/Html/Flex/`, `tests/Unit/Html/Flex/`
CSS Grid Layout (`css_grid_1`)	1	Verified	`src/Html/Grid/`, WPT derlemi
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`, `tests/Unit/Html/Cascade/`
CSS Table (`css_tables_3`)	3	Verified	`src/Html/Table/`, tablo fikstürleri + altın PDF’ler
CSS Fonts (`css_fonts_4`)	4	Verified	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

Örneğin text-align, text-indent ve color gibi özellikler matriste “Claimed” olarak derecelendirilmiştir (uygulanmış ancak ayrı bir modül fikstürü yok), bu nedenle burada Verified olarak listelenmemiştir.

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

HTML motoru hiçbir DOM tutmaz. Tuttuğu durum, skaler bir imleç ile bir push/pop stil yığınından oluşur; yalnızca boşluk içeren metin düğümleri belirteçlere ayırma sırasında atılır. Bunun sonucu olarak, sonraki bir öğe önceki bir öğeyi yeniden biçimlendiremez ve tam ağaç bağlamı gerektiren seçiciler (örneğin, karmaşık :has() durumları) ADR-006’ya göre kısıtlanır. Yalnızca belge sırasına bağlı bir yerleşim planlayın.

Katman sözleşmeleri (ADR-010)

Ayrıştırma, yerleşim ve boyama ayrı katmanlardır. Ayrıştırıcı ham boyama işleçleri üretmez ve yerleşim gönderimi CSS ayrıştırmaz. Bu sınırları aşmak, ADR-010’un yasakladığı bağlaşım borcudur. Tarif yazarları için bu, genel giriş noktasının writeHtml() olduğu anlamına gelir. Ayrıştırıcının iç yapılarına erişmeyin.

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

ADR-020’ye göre, kapsayıcı kapsamındaki biçimlendirme bağlamları (flex, table) bağlam başına 5,000 düğümle, 20 düzey derinlikle, etkin bağlamlar genelinde 50 MB etkin bellek tavanıyla ve 10 düzeylik iç içe geçmeyle sınırlı geçici bir alt ağaç oluşturabilir. Bu bağlamların dışında, akış modeli hiçbir ağaç tutmaz. Öngörülebilir bellek kullanımı için her tabloyu ve flex kapsayıcısını düğüm sınırı içinde tutun.

Güvenlik notları

HTML girdisini güvenilmez olarak ele alın. NextPDF betikleri çalıştırmaz ve varsayılan dış kaynak ilkesi rastgele uzak URL’leri getirmez, bu nedenle motorun kendisi temkinli davranır. Yine de, kullanıcı girdisinden derlediğiniz herhangi bir HTML’i işlemeden önce doğrulayın veya temizleyin. Öğe ve iç içe geçme üst sınırları da sizi korur: düşmanca veya hatalı bir belgenin ne kadar iş talep edebileceğini sınırlarlar.

Uygunluk

İfade	Belirtim	Madde	reference_id
CSS Text, kaynak metnin biçimlendirilmiş, satıra kaydırılmış metne çevrilmesini denetler.	W3C CSS Text Level 3	css_text_3#x1.x2.p4
Varsayılan gövde yazı tipi yüzü, standart bir Type 1 yazı tipine çözümlenir.	ISO 32000-2	iso32000_2_sec9#x1.x29

Bu tarif, NextPDF’in desteklenen bir HTML ve CSS alt kümesini nasıl işlediğini gösterir. Tam HTML veya tam CSS desteği ileri sürmez. Her modül için doğrulanmış durum CSS destek matrisinde yer alır.

Ticari bağlam

Geçerli değil.