HTML motorunun katman sözleşmeleri (ADR-010)

Bir bakışta

Köprü Metni İşaretleme Dili (HTML) alt sistemi, Basamaklı Stil Sayfaları (CSS) ayrıştırmayı, stil durumunu, yerleşimi ve boyamayı dört katmana ayırır. Bu katmanlar boyunca veri tek yönde akar. Mimari Karar Kaydı 010 (ADR-010), sınırları ve genişletme kurallarını tanımlar.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Mimari Karar Kaydı 010 (ADR-010) (“Engine Layer Contracts, Hot Path Ownership, and Extension Rules”, kabul tarihi 2026-04-12), HTML alt sisteminin nasıl katmanlandığını resmileştirir. Çekirdek işleme sözleşmesi dört katmandan oluşur: CSS ayrıştırma ve uygulayıcılar, stil durumu, yerleşim ve biçimlendirme ile boyama. ADR-010 ayrıca iki yardımcı katmanı belgeler: sayfalı ortam ve ölçüm test düzeneği. Bu katmanlar, veri akışını değiştirmeden dört katmanlı çekirdeği sarmalar. Sözlükte çekirdek için kullanılan kanonik terim “HTML işlem hattı” ifadesidir; bu, dört katmanlı bir işlem hattıdır.

Veri tek yönde akar. CSS metni, Katman 1’de türlenmiş değerlere dönüşür. Katman 1, bu değerleri Katman 2’deki HtmlStyleState alanlarına yazar. Katman 3, stil durumu alanlarını okur ve geometriyi hesaplar. Katman 4, değişmez bir ComputedStyle anlık görüntüsünü ve geometriyi okur, ardından Taşınabilir Belge Biçimi (PDF) işleçlerini üretir. Hiçbir katman, kendisinden sonraki bir katmandan okuma yapmaz.

Dört katmanlı ayrım, yalnızca belgelendirmeden ibaret değildir. ADR-010, v1.2.0 sürümünde uygulanan ve kodu doğru katmana taşıyan iki sınırlı yeniden düzenlemeyi kayıt altına alır. PageBorderPainter, HtmlParser içinden çıkarılmıştır; böylece boyama işleçleri artık düzenleyicinin içinde yer almaz. HtmlStyleState sınıfının docblock’u artık resmi katman sözleşmesini taşır ve her katmanın hangi alanları yazabileceğini veya okuyabileceğini belirtir.

Bir sınır açıkça belirtilmiştir. FormattingContextFactory::startTable() hâlâ beş ham CSS anahtarını doğrudan okur. ADR-010 bunu amaçlanan sözleşme olarak değil, gelecekteki bir TableApplicator için bilinen ve ertelenmiş teknik borç olarak kayıt altına alır. İstisnanın belgelenmesi, sözleşmenin bir parçasıdır.

Dört çekirdek katman

Katman	Dosyalar (temsili)	Yazar	Okur	Yapmamalı
1 — CSS ayrıştırma & uygulayıcılar	`CssValueParser`, `CssResolver`, `HtmlCssApplicator`, `src/Html/Applicator/*`	`HtmlStyleState` CSS alanları	Ham CSS metni	Geometriyi hesaplamak; işleçleri üretmek
2 — Stil durumu	`HtmlStyleState`, `State/ComputedStyle`, `State/LayoutState`	— (pasif değer torbası)	—	CSS ayrıştırmak; yerleşime karar vermek; işleçleri üretmek
3 — Yerleşim & biçimlendirme	`FormattingContextFactory`, `HtmlBlockHandler`, `FlexLayoutEngine`, `TableParser`, `FloatContext`	İmleç geometrisi	`HtmlStyleState` alanları	Ham `$css[...]` okumak; boyama işleçleri üretmek
4 — Boyama & işleme	`BorderRenderer`, `BackgroundImageRenderer`, `src/Html/Paint/`, `src/Html/Gradient/`	PDF işleç akışı	`ComputedStyle` (değişmez) + geometri	Geometriyi hesaplamak; CSS ayrıştırmak; sayfa sonlarına karar vermek

İki yardımcı katman

Katman	Dosyalar (temsili)	Rol
5 — Sayfalı ortam	`PageBreakController`, `PageBorderPainter`, `PageRule`, `PageRuleParser`, `ParserConfigurator`	Sayfa `@page` kurallarını çözümlemek; sonlandırma ile orphan/widow kısıtlarını değerlendirmek; sayfa süslemesini boyamaya devretmek.
6 — Ölçüm & test düzeneği	Web Platform Tests (WPT) sınıflandırıcı betikleri, `tests/Support/*`	Test sonuçlarını sınıflandırmak; regresyon anlık görüntüleri üretmek; doğrulama yardımcıları sağlamak. Hiçbir işleme mantığı taşımaz.

API yüzeyi

Sözleşme, sınıf yerleşimi ve HtmlStyleState docblock’u aracılığıyla uygulanır. Bunu src/Html/ ile karşılaştırarak doğrulayın.

Simge	Katman	Sözleşme rolü
`PropertyApplicatorInterface`	1	Strateji arabirimi; CSS hesaplanmış alanları yazan tek yerdir.
`ParserConfigurator::buildCssApplicator()`	1 (bağlama)	Her uygulayıcıyı kaydeder. Yeni bir CSS özelliği burada kaydedilir.
`HtmlStyleState`	2	Çift gruplu torba; sınıf docblock’u, her alanın sahibi olan katmanı belirtir.
`HtmlStyleState::toComputedStyle()`	2	Boyama katmanı için değişmez `ComputedStyle` nesnesini üretir.
`FormattingContextFactory::dispatchOpenTag()`	3	Yeni yerleşim davranışı için tek yönlendirme noktası.
`PageBorderPainter::buildStream()`	4	Sayfa süslemesi; Katman 5’ten çağrılır, `HtmlParser` içine satır içine alınmaz.

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

Katmanlara hiçbir zaman doğrudan müdahale etmezsiniz. Dört katmanlı akış, tek bir çağrı içinde çalışır.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();
$doc->writeHtml('<p style="color:#1E3A8A;border:1px solid #999;">Layered render.</p>');
$doc->save(__DIR__ . '/output/layers.pdf');

Kod örneği — üretim

Sözleşme, kitaplığı çağırdığınızda değil, katkıda bulunduğunuzda önem taşır. Bir CSS özelliği eklemek için Katman 1 genişletme noktasını kullanın: bir uygulayıcı oluşturun, katman docblock’u bulunan türlenmiş bir HtmlStyleState alanı ekleyin ve uygulayıcıyı ParserConfigurator içinde kaydedin. Aşağıdaki örnek, uygulayıcı sözleşmesinin biçimini gösterir. Somut bir sınıf için src/Html/Applicator/ dizinini model alın.

<?php

declare(strict_types=1);

// Layer 1 extension contract (see ADR-010 §C "New CSS property").
// A new property group ships as a PropertyApplicatorInterface
// implementation registered in ParserConfigurator::buildCssApplicator().
// It writes a typed HtmlStyleState field and never computes geometry
// or emits PDF operators — those belong to Layers 3 and 4.

Uç durumlar & tuzaklar

FormattingContextFactory::startTable() ham CSS’i okur. Bu, belgelenmiş tek sözleşme istisnasıdır ve gelecekteki bir TableApplicator için ertelenmiştir. Bu deseni kopyalamayın.
Altı katman, dört katmanlı çekirdek. ADR-010 altı katmanı numaralandırır. Veri akışı sözleşmesi, dört katmanlı çekirdektir; sayfalı ortam ve ölçüm yardımcı katmanlardır.
HtmlStyleState çift gruplu yapıdır. Hesaplanmış CSS alanları ile yerleşim izleme alanlarını taşır. CSS grubunu yalnızca uygulayıcılar yazar. Boyama, ComputedStyle’ı okur; yerleşim izleme alanlarını asla okumaz.
HtmlParser hiçbir katmana ait değildir. Bir düzenleyicidir. CSS ayrıştırma, geometri hesabı ve boyama işleçlerinin üretimi onun içinde yer almamalıdır.

Performans

Katman sözleşmesi yapısaldır; bu nedenle çalışma zamanında ek bir maliyet getirmez. HtmlStyleState::toComputedStyle(), boyama gerektiren her öğe için tek bir değişmez anlık görüntü üretir. Bu anlık görüntü, boyama kodunun değişebilir durum torbasından kaçınmasını sağlar. İşleme maliyeti, katmanlama tarafından değil, akış modeli tarafından yönetilir. Sayfa başına performance_budget (wall_ms: 1500, peak_mb: 64) işlevsel üst sınır olarak kalır.

Güvenlik notları

Katman ayrımı, güvenlik modelini destekler. Katman 1, CSS değerlerini yerleşim veya boyama kodu görmeden önce ayrıştırır ve ilkeye göre filtreler; böylece DefaultHtmlSecurityPolicy::isCssPropertyAllowed() tek geçit noktası olmaya devam eder. Boyama, saldırgan denetimindeki ham CSS’i asla okumaz. HTML modülü güvenlik modeli bölümüne bakın.

Uygunluk

Bu sayfa, harici bir standarda atıfta bulunmaz. Katman sınırları, ADR-010’dan ve sözleşmeyi kaynak içinde kodlayan HtmlStyleState sınıfının docblock’undan gelir. CSS davranışsal uygunluğu css-resolver sayfasında belgelenmiştir.

Ticari bağlam

Kurumsal yetenek. Premium CSS özellikleri, belgelenmiş genişletme noktaları aracılığıyla bu dört katmanın aynısını kullanır. Ayrı bir Premium işlem hattı yoktur. CSS destek matrisi bölümüne bakın.