İçerik: metinsel + yapısal içerik modeli

Bir bakışta

Content modülü metin gösterme işleçlerini, metin durumu işleçlerini, metin gölgelerini, belge düzeyindeki JavaScript’i ve işaretli içerik özellik sözlüklerini oluşturur. Yerleşim ile içerik akışı arasında konumlanır.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Content, çözümlenmiş metni Taşınabilir Belge Biçimi (PDF) işleçlerine dönüştüren ilkelleri sağlar. TextRenderer merkezi bileşendir. Bir dize için metin gösterme işlecini ve ondan önce gelen metin durumu işleçlerini oluşturur. Uluslararası Standardizasyon Örgütü (ISO) 32000-2 §9 kapsamında Tj işleci, bir dizenin gliflerini geçerli yazı tipi ve metne ilişkin grafik parametreleriyle boyar. TextRenderer, tek bir gösterme işleci ile konumlandırılmış bir TJ dizisi arasında, etkin TypographyMode değerine göre seçim yapar. Kip TJ dizilerini kullandığında kerning ayarlamaları uygular.

Metin durumu, eksiksiz bir küme olarak modellenir. setTextRenderingMode(), bir TextRenderingMode enum değeri alır. Sekiz durumun her biri ISO 32000-2 metin işleme kiplerine birebir eşlenir: dolgu, kontur, önce dolgu sonra kontur, görünmez ve dört kırpma çeşidi (Tablo 104). İşleyici ayrıca kontur genişliğini, karakter aralığını, sözcük aralığını, yatay esnetmeyi, metin yükselişini, sağdan sola yönü ve isteğe bağlı bir Hyphenator bileşenini denetler. buildTextStateOperators() çağrısı, biriken durumu tek bir işleç bloğu olarak yayımlar.

TextShadow bir değer nesnesidir: renk, kullanıcı birimleri cinsinden X ve Y kaymaları ve opaklık. İşleyici bunu, kaydırılmış ikinci bir çizim geçişi yayımlamak için kullanır. Varsayılan kaymalar, Basamaklı Stil Sayfalarındaki (CSS) yumuşak bir gölgeye benzer biçimde, 0,5 opaklıkla kullanılan ince bir 0.5/−0.5 kayma değeridir.

JavaScriptManager, belge düzeyindeki betik yürütmeden sorumludur. includeJs() bir belge betiği kaydeder. addJsObject() adlandırılmış bir betik nesnesi kaydeder. writeJavaScript() / writeOpenAction() betikleri kataloğa ve OpenAction’a serileştirir. Yönetici, yayımlamadan önce her betik gövdesini doğrular ve PDF dizesi olarak kodlar.

PropertiesRegistry işaretli içerik özellikleri deposudur. register(), bir özellik sözlüğü için kararlı bir etiket dizini döndürür. registerOcg() / registerOcgs() isteğe bağlı içerik gruplarını (OCG) nesne numarasıyla ilişkilendirir. writeProperties(), kayıt defterini sayfa kaynakları sözlüğüne serileştirir. ContentStream modülü, bir özellik listesiyle işaretli bir sıra açtığında bu veriyi okur.

Bu modülde, PDF’ye özgü doğrudan geçiş biçimlerini işlemek için iki görüntü çözücüsü bulunur. JBig2Loader ve JpxLoader, JBIG2 ve JPEG 2000 segment yapılarını ayrıştırır ve pikselleri tarama dönüşümüne sokmadan ImageData döndürür. Kodlanmış baytlar görüntüleyiciye değiştirilmeden aktarılır. Bir JBIG2 kaynağı ayrı bir globals segmenti taşıdığında, JBig2Loader bunu görüntü XObject’i üzerindeki bir /JBIG2Globals akış başvurusu aracılığıyla gömer; in-stream/in-line biçimi ise eskisi gibi tam gidiş-dönüş doğruluğunu korur. Bu yalnızca yapısal bağlantıdır: globals baytları için iddia, çözülmeden aktarılmaları değil, tarama dönüşümüne sokulmadan aktarılmalarıdır.

API yüzeyi

Sınıf	Temel yöntemler	Rol
`TextRenderer`	`buildTextShowOperator()`, `buildTextStateOperators()`, `setTextRenderingMode()`, `setTextStrokeWidth()`, `setTextShadow()`, `setFontSpacing()`, `setWordSpacing()`, `setFontStretching()`, `setTextRise()`, `setRTL()`, `setHyphenation()`	Metin gösterme + metin durumu işleç oluşturucusu
`TextRenderingMode` (enum)	`Fill`, `Stroke`, `FillStroke`, `Invisible`, `FillClip`, `StrokeClip`, `FillStrokeClip`, `Clip`	ISO 32000-2 metin işleme kipleri
`TextShadow`	`__construct(Color, offsetX, offsetY, opacity)`	Kaydırılmış çizim geçişi değer nesnesi
`JavaScriptManager`	`includeJs()`, `addJsObject()`, `hasJavaScript()`, `writeJavaScript()`, `writeOpenAction()`	Belge düzeyinde JavaScript için katalog bağlantısı
`PropertiesRegistry`	`register()`, `getTagIndex()`, `registerOcg()`, `registerOcgs()`, `getAll()`, `writeProperties()`	İşaretli içerik + OCG özellik deposu
`JBig2Loader`	`load()`, `loadFromString()`, `parseSegments()`	JBIG2 doğrudan geçiş çözücüsü
`JpxLoader`	`load()`, `loadFromString()`, `parseBoxes()`	JPEG 2000 doğrudan geçiş çözücüsü

Tam PHPDoc tablosu için composer docs:generate-api-php -- --module=Content komutunu çalıştırın.

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

Kaynak: examples/28-text-rendering.php.

<?php

declare(strict_types=1);

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

use NextPDF\Content\TextRenderer;
use NextPDF\Content\TextRenderingMode;

$renderer = new TextRenderer();
$renderer
    ->setTextRenderingMode(TextRenderingMode::FillStroke)
    ->setTextStrokeWidth(0.3)
    ->setWordSpacing(0.5);

$stateOps = $renderer->buildTextStateOperators();

Kod örneği — üretim

Bu örnek yumuşak bir gölge ve tireleme ekler; ardından gösterme işlecini çağıranın sağladığı bir kaçış işleviyle, yani mimari karar kaydı ADR-015’teki kanonik PdfStringEscaper sınırıyla oluşturur.

<?php

declare(strict_types=1);

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

use NextPDF\Content\TextRenderer;
use NextPDF\Content\TextShadow;
use NextPDF\Graphics\Color;
use NextPDF\Support\PdfStringEscaper;

$renderer = new TextRenderer();
$renderer
    ->setTextShadow(new TextShadow(Color::rgb(0, 0, 0), 0.4, -0.4, 0.45))
    ->setRTL(false);

$showOp = $renderer->buildTextShowOperator(
    text: 'Quarterly report',
    fontKey: 'F1',
    metrics: $fontMetrics,
    escapeSegment: static fn (string $s): string => PdfStringEscaper::escapeLiteral($s),
);

$pageContent = $renderer->buildTextStateOperators() . $showOp;

Uç durumlar & tuzaklar

buildTextShowOperator(), boş girdi için boş bir dize döndürür. Boş bir Tj yayımlamayın; yerleşiminiz boş diziler üretebiliyorsa üst akışta koruma uygulayın.
Kaçış geri çağrısı zorunludur ve dize güvenliğinden sorumludur. ADR-015’teki kanonik PdfStringEscaper::escapeLiteral() işlevini geçirin. Eksik bir kaçış işleyicisi, sözdizimsel olarak geçersiz bir hazır değer dizesi üretir.
Başlangıç noktası sol üstteyken TextShadow::offsetY aşağı yönde negatiftir. Pozitif bir Y değeri gölgeyi yukarı iter; bu ise nadiren istenen bir durumdur.
JavaScriptManager betik girdisini doğrular. Geçersiz betik gövdeleri, yazma anında sessizce atılmaz; kayıt anında reddedilir.
JBig2Loader ve JpxLoader hiçbir zaman tarama dönüşümü yapmaz. Kodlanmış baytları doğrular ve doğrudan geçirir. Bozuk bir segment, boş bir görüntü olarak değil, bir ayrıştırma hatası olarak ortaya çıkar.
PropertiesRegistry::register() sözlük düzeyinde idempotent çalışır; özdeş özellik sözlükleri tek bir etiket dizinini yeniden kullanır.

Performans

İşleç oluşturma, dize uzunluğuna göre O(n)‘dir; tipografi kipi TJ dizilerini kullandığında buna bir O(n) kerning geçişi eklenir. Bu aşamada yerleşim veya şekillendirme maliyeti yoktur; bu iş Typography ve Layout modüllerinde kalır. JavaScript ve özellik serileştirmesi O(girdi sayısı)‘dır. Doğrudan geçiş görüntü yükleyicileri, sıfır çözme maliyetiyle O(bayt) ayrıştırma kullanır. Bu, taranmış belge iş yüklerinde temel avantajlarıdır. Başvuru iş yükü için performance_budget değeri 1500 ms duvar saati süresi ve 64 MB tepe bellek kullanımıdır.

Güvenlik notları

JavaScriptManager, güvenilmeyen şablonlardan gelebilecek betik gövdelerini kabul eder. Her gövdeyi doğrular ve PDF dizesi olarak kodlar; ancak belge JavaScript’i aktif içerik yüzeyi olarak kalır. Güvenilmeyen çıktılarda bunu devre dışı bırakın ya da /modules/core/security/ içinde açıklanan temizleme yoluyla kaldırın. JBig2Loader ve JpxLoader güvenilmeyen segment yapılarını ayrıştırır: girdi boyutunu ve ayrıştırma süresini sınırlayın ve kaynak kullanıcı tarafından sağlanıyorsa ayrıştırmayı kısıtlanmış bir işçide çalıştırın. Metin kaçış sınırı, çağıran tarafından sağlanan geri çağrıdır. Denetim baytlarının bir hazır değer dizesinin dışına çıkamaması için her zaman kanonik kaçış işleyicisini geçirin.

Uygunluk

Modül, ISO 32000-2 §9 metin modeliyle tutarlı metin gösterme ve metin durumu işleçleri yayımlar. Buna, Tj işleci anlam bilgisi ve TextRenderingMode enum’ı tarafından yansıtılan Tablo 104 işleme kipleri dahildir. Bunlar uygulama düzeyindeki gerçeklerdir: src/Content/TextRenderer.php ve TextRenderingMode enum’ı işleç biçimlerini üretir; tests/Unit/Content/TextRenderer*, JavaScriptManagerIsoTest ve PropertiesRegistryTest bunları sınar. Bunlar uçtan uca PDF 2.0 uygunluğunu ileri sürmez. Dize kaçış sözleşmesi, ADR-015 ile ISO 32000-2 §7.3.4.2 hükmünü izler. JBIG2 ve JPEG 2000 doğrudan geçiş yolları, kodlanmış akışları değiştirmeden korur. Ayrı bir JBIG2 globals segmenti, görüntü XObject’i üzerinde bir /JBIG2Globals akış başvurusu olarak gömülür; bu, bir çözme doğruluğu savı olarak değil, yapısal bağlantı olarak doğrulanır. Belge düzeyinde uygunluk, /modules/core/conformance/ içindeki oracle ve golden paketleri tarafından doğrulanır.