Boru hattı modeli

Spec Spec: ISO 32000-2, §7.5 ISO 32000-2 §7.5 Evidence { } Code-backed Evidence: Code-backed

Bir bakışta

Bir NextPDF belgesi tek, belirsiz bir adımda üretilmez. Az sayıda açık aşamadan geçer: niyeti kaydeden bir cephe, niyeti bir modele dönüştüren bir içerik katmanı ve bu modeli uyumlu bir PDF’ye serileştiren bir yazıcı. Bu sayfa bu yapıyı ve motor için neden doğru tercih olduğunu açıklar.

Bunun neden önemli olduğu

PDF dosya biçimi başlı başına katmanlı bir yapıdır — bir başlık, bir nesneler gövdesi, bir çapraz başvuru tablosu ve bir fragman — ve bir yazıcının bunların tümünü tutarlı biçimde bir araya getirmesi gerekir. Bu yapıyı oluşturan motor tek ve karmaşık bir yordamdan ibaretse, her değişiklik her çıktıyı riske atar. Bu durumda güven kazanmanın tek yolu, belgelerin tamamını işlemek ve gözle incelemektir; bu da yavaş, geç ve ikna edici olmayan bir yöntemdir.

Açık bir boru hattı bunu tersine çevirir. Her aşamanın tek bir işi ve türlenmiş bir sınırı vardır; böylece bir değişikliği yalnızca dosyanın sonunda değil, dokunduğu aşamada değerlendirebilir ve test edebilirsiniz. Bu mimari, her şeyden önce bir test edilebilirlik ve genişletilebilirlik kararıdır.

Kısa özet

• Genel giriş noktası bir Document cephesidir. Bu; nasıl serileştirildiğini değil, neyi istediğinizi kaydeden akıcı, tek kullanımlık, worker güvenli bir oluşturucudur.
• Cephe, görevi yaklaşık yirmi dört odaklı sorumluluk trait’ine (metin çıktısı, çizim, sayfalar, güvenlik, gezinme vb.) devreder — dev bir sınıf yerine her birinin tek bir sorumluluğu vardır.
• İçerik iki yoldan biriyle gelir: doğrudan çizim (grafik temel öğeleri) veya HTML/CSS motoru. Her ikisi de aynı iç belge modelini üretir.
• Adanmış bir PDF yazıcısı, bir PDF 1.4 / 1.7 / 2.0 stratejisi seçerek bu modeli serileştirir. Geçerli dosya yapısını üretme işi burada yapılır, başka hiçbir yerde değil.
• Uzun ömürlü durum (yazı tipi ve görüntü kayıt defterleri) süreç kapsamındadır ve paylaşılır; istek başına durum (belge) her seferinde yeniden oluşturulur ve asla yeniden kullanılmaz. Sınır açıktır; worker çalışma zamanlarını güvenli kılan da budur.

NextPDF buna nasıl yaklaşır

Modeli görmenin en temiz yolu, bir belgeyi çağrıdan bayt çıktısına kadar izlemektir.

1. Document facade Fluent, use-once builder; records intent via concern traits.
2. Content production Direct drawing or the HTML/CSS engine — both build one document model.
3. Document model Accumulated pages, content, and resources held as typed state.
4. PDF writer Serialises the model; selects a PDF 1.4 / 1.7 / 2.0 strategy.
5. Conforming PDF Header, object body, cross-reference table, trailer.

Bir belgenin NextPDF içindeki yolu: her aşamanın tek bir sorumluluğu ve türlenmiş bir sınırı vardır; böylece yalıtılmış olarak değerlendirilebilir ve test edilebilir.

İki tasarım tercihi, bu yapıyı bir diyagramdan fazlası hâline getirir.

Cephe bileşiktir, yekpare değildir. Document her özelliği kendisi uygulamaz; her alanı adanmış bir sorumluluk trait’ine devreder — metin çıktısı, çizim, sayfalar, güvenlik, tipografi, gezinme, işlemler vb. Yeni bir belge yöntemi, cephenin kendisinde değil, ilgili alanın sahibi olan trait’te yer alır. Çağırdığınız sınıf küçük kalır ve sorumluluklar ayrı tutulur.

Dosya yapısı yalnızca yazıcıya aittir. İçerik üretimi hangi işaretlerin ve nesnelerin var olduğuna karar verir; yazıcı ise hangi sürüm stratejisinin uygulanacağı dâhil, bunların nasıl geçerli bir PDF dosyasına dönüştüğüne karar verir. Bu ayrım mimari bir kural olarak zorunlu kılınır: yerleşim ve içerik kodu nihai dosya yapısını üretmez, yazıcı da yerleşim kararları vermez. Bunun yararı, “çıktı geçerli bir PDF mi?” sorusunun test edileceği tam olarak tek bir yer bulunmasıdır.

Yaşam süresi sınırı, sonradan düşünülmüş bir ek değil, modelin bir parçasıdır. Yazı tipi ve görüntü kayıt defterleri süreç ömrü boyunca yaşar ve istekler arasında paylaşılır; belge, işleme bağlamı ve yazıcı ise istek başına oluşturulur ve elden çıkarılır. Bir worker çalışma zamanında bu ayrım, güvenli yeniden kullanım ile istekler arası bozulma arasındaki farktır. Bu nedenle bu durum geliştirici disiplinine bırakılmaz, mimaride açıkça belirtilir.

Kanıtların söyledikleri

Bu sayfa Evidence { } Code-backed Evidence: Code-backed niteliğindedir. Aşamalar, core deposundaki gerçek yapıyla eşleşir:

• Cephe ve onun devretme yapısı, src/Core/Document.php ile src/Core/Concerns/ içindeki sorumluluk trait’leridir (metin çıktısı, çıktı, çizim, sayfalar, güvenlik, tipografi, gezinme, işlemler ve daha fazlası — her biri tek bir sorumluluk).
• İki içerik yolu, HTML/CSS motoru (src/Html/) ve doğrudan çizimdir (src/Graphics/); her ikisi de iç modeli besler.
• Serileştirme ve PDF sürüm stratejisi src/Writer/ içinde bulunur (PdfWriter.php, açık PDF 1.4 / 1.7 / 2.0 strateji sınıflarıyla birlikte).
• Süreç yaşam süresi ile istek başına yaşam süresi arasındaki sınır, mimari genel bakışında kayıt altına alınan ve dağıtılan worker-factory örneğiyle uygulanan worker güvenli tasarımdır; bu örnek, istekler arasında bir FontRegistry ve ImageRegistry paylaşırken her Document belgesini her seferinde yeniden oluşturur.

Hedefi biçim belirler. Yazıcının çıktısı; bir başlık, bir nesne gövdesi, bir çapraz başvuru tablosu ve bir fragmandan oluşan, şu standarda uygun bir yapı olmalıdır: Spec Spec: ISO 32000-2, §7.5 ISO 32000-2 §7.5 . Bu yükümlülüğü tek bir aşamada toplamak, motorun geri kalanının dosya yapısını bir araya getirmek yerine içeriğe odaklanmış kalmasını sağlayan şeydir.

Pratik örnek

Cephenin görevi, niyetin doğrudan niyet olarak okunmasını sağlamaktır. İçerik yolu ve yazıcı, çağrı noktasında görünmez kalır:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();   // facade
$doc->setTitle('Quarterly Report');    // metadata concern
$doc->addPage();                       // pages concern
$doc->setFont('helvetica', 'B', 16);   // typography concern
$doc->cell(0, 12, 'Summary', newLine: true); // text-output concern
$doc->writeHtml('<p>Generated in-process.</p>'); // HTML content path
$doc->save(__DIR__ . '/report.pdf');   // writer stage

Her çağrı farklı bir sorumluluğa karşılık gelir. İki farklı içerik yolu aynı modeli besler. Tam olarak tek bir aşama — save() — modeli dosya baytlarına dönüştürür. Çağrı noktasındaki hiçbir öğenin, çapraz başvuru tablosunun nasıl oluşturulduğunu bilmesi gerekmez.

Yaygın yanlış anlama

Yaygın bir yanlış okuma, “boru hattı” ifadesinin, bir Unix borusu gibi aşama aşama bağladığınız akış tabanlı bir push API’sini ima ettiğidir. Oysa öyle değildir. Buradaki boru hattı mimari bir ayrıştırmadır: tek sorumlulukları ve türlenmiş sınırları olan aşamalar. Yine de akıcı bir cepheye karşı programlama yaparsınız. Aşamalar, motorun nasıl oluşturulup test edildiğini ifade eder; elle kurduğunuz bir taşıma katmanı değildir.

Bununla ilişkili bir hata, cephenin motorun kendisi olduğunu varsaymaktır. Cephe, giriş noktasıdır. Asıl iş; sorumluluk trait’leri, iki içerik yolu ve bir yazıcı arasında dağıtılır. Tek bir özellik değişikliğinin her çıktıyı riske atmamasının nedeni tam da bu dağıtımdır.

Human-factors note: Human-factors note

Aynı beş aşamalı dizi; diyagramda, kısa özette, kanıtlarda ve örnekte bilinçli olarak kullanılır. Okuyucunun bir kez karşılaşıp ardından her yerde tanıdığı tutarlı bir yapı, sayfayı takip etme çabasını azaltır. Bu durum, motorun kendisinin aşama sınırlarını neden çok ve değişken yerine sabit ve az tuttuğunu yansıtır.

Sınırlamalar ve kapsam

Bu sayfa, herhangi bir aşamanın iç API’sini değil, boru hattının yapısını açıklar. Tam sorumluluk trait’i envanteri, yazıcı strateji seçim kuralları ve içerik modeli alanları bu açıklamayla değil, kod ve başvuru belgeleriyle tanımlanır. Kesin trait sayısı, modeli değiştirmeden değişebilen bir uygulama ayrıntısıdır. Bu sayfa, HTML motorunun iç aşamalarını (ayrı bir konu) veya yazıcının akış ve bellek davranışını (yine ayrı) kapsamaz. Yapısal iddialar, bu sayfanın gözden geçirilme tarihi itibarıyla doğrudur; yetkili kaynak, core deposunun src/Core/, src/Html/, src/Graphics/ ve src/Writer/ dizinleridir.

Boru hattı modeli tüm sürümlerde aynıdır; sürümler yeni aşamalar değil, mevcut aşamalar içinde yetenekler ekler:

Pipeline model — edition availability

Edition	Availability
Core	○ Core, tam cephe → içerik → yazıcı boru hattını uygular.
Pro	○ Pro, yeni aşamalar değil, mevcut aşamalar içinde yetenekler ekler.
Enterprise	○ Enterprise, yeni aşamalar değil, mevcut aşamalar içinde yetenekler ekler.

İlgili belgeler

• Bellek ve akış — yazıcı aşamasının belleği nasıl sınırlı tuttuğunu açıklar.
• HTML boru hattı — HTML içerik yolunun iç aşamaları.
• Her yerde katı türler — her aşamayı bağımsız olarak test edilebilir kılan türlenmiş sınırlar.

Sözlük

• Cephe — genel Document giriş noktası: niyeti kaydeden ve sorumluluk trait’lerine devreden, akıcı, tek kullanımlık bir oluşturucu.
• Sorumluluk trait’i — cephenin bir araya getirdiği, her biri tek bir özellik alanına (metin çıktısı, çizim, sayfalar, güvenlik vb.) sahip odaklı bir PHP trait’i.
• İçerik yolu — içeriğin modele girdiği iki yoldan biri: doğrudan çizim veya HTML/CSS motoru.
• Belge modeli — motorun serileştirmeden önce sayfalar, içerik ve kaynaklar için tuttuğu türlenmiş iç birikim.
• Yazıcı aşaması — bir PDF 1.4 / 1.7 / 2.0 stratejisi seçerek modeli geçerli bir PDF’ye serileştiren bileşen.
• Worker güvenli — süreç yaşam süresi durumu güvenli biçimde paylaşılırken istek başına durumun her seferinde yeniden oluşturulduğu ve asla yeniden kullanılmadığı şekilde tasarlanmış.