Writer: PDF 2.0 seri hâle getiricisi + xref

Bir bakışta

Writer modülü, bir belgeyi Taşınabilir Belge Biçimi (PDF) baytları olarak seri hâle getirir. Bir sürüm stratejisi seçer, nesne grafiğini yazar ve çapraz başvuru yapısını fragmanla birlikte çıktıya yazar.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Giriş noktası olarak PdfWriter kullanın. DocumentData değer nesnesini write() yöntemine geçirin. Bu yöntem, tam PDF’yi bir bayt dizesi olarak döndürür. Yazıcı nesne grafiğini bir araya getirir, nesne numaralarını atar, bayt uzaklıklarını kaydeder ve çapraz başvuru yapısını en sona yazar.

Yazıcı, her çağrıda tek bir seri hâle getirme stratejisi kullanır. PdfSerializationStrategy arabirimi dört yöntem tanımlar: writeHeader(), getCatalogVersion(), writeXrefAndTrailer() ve usesXrefStream(). Bu arabirimi üç strateji uygular. Pdf20StreamStrategy, %PDF-2.0 başlığını yazar, katalog sürümünü /2.0 olarak ayarlar ve bir çapraz başvuru akışı çıktıya yazar. Pdf17TableStrategy, %PDF-1.7 ve klasik bir çapraz başvuru tablosu yazar. Pdf14TableStrategy, %PDF-1.4 ve bir çapraz başvuru tablosu yazar. PdfWriter, stratejiyi match ile DocumentData::$outputProfile üzerinde seçer. Varsayılan değer Pdf20StreamStrategy’dir.

Üç hedef sürüm PdfOutputProfile enum’unda yer alır: Pdf20, Pdf17 ve Pdf14. headerVersion(), catalogVersion(), allowsObjectStreams() ve usesXrefStream() yöntemlerini açığa çıkarır. Bir arşivsel uygunluk kipi, strateji seçiminden önce seçilen profili geçersiz kılar. Pdf14FeatureGuard, profil Pdf14 olduğunda PDF 2.0 özelliklerini reddeder.

ISO 32000-2 §7’de tanımlandığı gibi, bir çapraz başvuru akışı her nesne numarasını bayt uzaklığına eşler. ISO 32000-2 §7.5.6’da tanımlandığı gibi, artımlı güncellemeler yeni nesneleri dosyanın sonuna ekler. Yazıcı, her sabit dizeyi ISO 32000-2 §7.3.4.2 (ADR-015) içindeki normatif kaçış tablosunu izleyen kanonik PdfStringEscaper::escapeLiteral() yolundan geçirerek kaçış uygular.

Yazıcı, deterministik çıktıyı destekler. setDeterministicMode(), nesne tanımlayıcılarını ve sözlük anahtarı sırasını sabitler. setReproducibleClock(), belge zaman damgasını sabitler. Her iki sabitleme de ayarlandığında, sabit bir girdi bayt düzeyinde özdeş çıktı üretir. writeChunked() yöntemi, PDF’yi sabit boyutlu parçalar hâlinde döndüren bir üreteç verir. Streaming/StreamingPdfWriter, bellek bütçesini aşan belgeler için, çağıranın sağladığı bir akışa her seferinde bir sayfa yazar.

Linearizer, tamamlanmış bir PDF’yi doğrusallaştırılmış bir yerleşime yeniden yazar. İlk sayfayı erken yerleştirir, böylece bir görüntüleyici, tam indirme tamamlanmadan önce onu gösterebilir. shadowValidate(), yeniden yazmayı girdiyi değiştirmeden denetler.

Dikkat. PdfWriter.php ve Linearizer.php, bayt uzaklıkları ve nesne grafiği açısından kritiktir (bildirilmiş tehlike bölgeleri). Writer golden paketi olmadan nesne numaralandırmasını veya xref uzaklığı aritmetiğini değiştirmeyin.

API yüzeyi

Sınıf	Anahtar yöntemler	Rol
`PdfWriter`	`write(DocumentData): string`, `writeChunked(DocumentData, int): Generator`, `setDeterministicMode()`, `setReproducibleClock()`, `setOutputColorProfile()`, `getLastXrefOffset()`, `getFileId()`	Birincil seri hâle getirici
`PdfSerializationStrategy` (arabirim)	`writeHeader()`, `getCatalogVersion()`, `writeXrefAndTrailer()`, `usesXrefStream()`	Sürüm stratejisi sözleşmesi
`Pdf20StreamStrategy`	`writeHeader()` → `%PDF-2.0`, `getCatalogVersion()` → `/2.0`, `usesXrefStream()` → `true`	PDF 2.0 xref-akışı stratejisi
`Pdf17TableStrategy`	`writeHeader()` → `%PDF-1.7`, xref tablosu	PDF 1.7 xref-tablosu stratejisi
`Pdf14TableStrategy`	`writeHeader()` → `%PDF-1.4`, xref tablosu	PDF 1.4 xref-tablosu stratejisi
`PdfOutputProfile` (enum)	`Pdf20`, `Pdf17`, `Pdf14`; `headerVersion()`, `catalogVersion()`, `allowsObjectStreams()`	Hedef sürüm seçici
`PdfXrefWriter`	`generateFileId()`, `finalizeTrailerAndXref()`	Dosya kimliği + trailer/xref sonlandırma
`Linearizer`	`linearize(string): string`, `shadowValidate(string): array`	Hızlı web görünümü yeniden yazımı
`Streaming\StreamingPdfWriter`	`open()`, `newPage()`, `close()`	Tek geçişli akış yazıcısı

Tam PHPDoc tablosunu oluşturmak için composer docs:generate-api-php -- --module=Writer komutunu çalıştırın.

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

Kaynak: examples/02-pdf-factory.php.

<?php

declare(strict_types=1);

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

use NextPDF\Writer\PdfWriter;

$writer = new PdfWriter();
$pdfBytes = $writer->write($documentData);

file_put_contents('out.pdf', $pdfBytes);

Varsayılan profil PDF 2.0’dır. Çıktı %PDF-2.0 ile başlar ve bir çapraz başvuru akışıyla biter.

Kod örneği — üretim

Bu örnek, bayt düzeyinde özdeş çıktı için determinizmi ve sabit bir saati ayarlar; ardından sonucu sabit parçalar hâlinde akıtır.

<?php

declare(strict_types=1);

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

use DateTimeImmutable;
use NextPDF\Writer\PdfWriter;
use NextPDF\Writer\ReproducibleClock;

$pinned = new DateTimeImmutable('2026-01-01T00:00:00Z');

$writer = new PdfWriter();
$writer->setDeterministicMode($pinned, 'nextpdf-fixed-file-id');
$writer->setReproducibleClock(new ReproducibleClock($pinned));

$out = fopen('php://output', 'wb');
foreach ($writer->writeChunked($documentData, chunkSize: 65536) as $chunk) {
    fwrite($out, $chunk);
}
fclose($out);

Sınır durumlar ve tuzaklar

Her write() çağrısında yalnızca bir strateji çalışır. Yazıcı her çağrıda stratejiyi profilden sıfırlar. Önceki bir çağrının sürümü sızmaz.
Bir arşivsel uygunluk kipi, istenen profili geçersiz kılar. Bir PDF/A-3 derlemesi PDF 1.7’yi zorunlu kılar. Bir PDF/A-4 derlemesi PDF 2.0’ı zorunlu kılar.
Bayt düzeyinde özdeş çıktı her iki sabitlemeyi de gerektirir. Deterministik kipi ve yeniden üretilebilir bir saati ayarlayın. Tek başına bir sabitleme yeterli değildir.
writeChunked() bir üreteç döndürür. Onu tamamen tüketin. Kısmi bir okuma, kesik ve geçersiz bir PDF üretir.
Linearizer, çapraz başvuru uzaklıklarını yeniden yazar. Başarısız bir yeniden yazmayı tolere edemeyen bir işlem hattında önce shadowValidate() çalıştırın.
Pdf14TableStrategy, final readonly niteliğindedir. PDF 1.4 yolu, PDF 2.0 özelliklerini Pdf14FeatureGuard aracılığıyla reddeder; onları alt sürüme düşürmez.

Başarım

Seri hâle getirme, nesne sayısına ve toplam bayt boyutuna göre doğrusaldır. Çapraz başvuru akışı, nesne tablosu üzerinde ek bir geçiş yapar. writeChunked(), bir araya getirilmiş belgeyi tutar ancak onu sınırlı dilimler hâlinde verir; bu nedenle en yüksek bellek kullanımı belge boyutu artı bir parçadır. Streaming\StreamingPdfWriter belgenin tamamını bellekte tutmaz; bellek bütçesinden daha büyük girdiler için onu kullanın. Referans iş yükü bütçesi 1500 ms duvar saati ve 64 MB en yüksek bellektir. Doğrusallaştırma, ikinci bir tam geçiş ve bir ölçüm geçişi ekler. Bunun için açıkça bütçe ayırın.

Güvenlik notları

Yazıcı, güvenilir bir bellek içi nesne grafiğini seri hâle getirir. Girdiler ana tehdit sınırıdır. Her sabit dize kanonik PdfStringEscaper::escapeLiteral() (ADR-015) yolundan geçer, böylece gömülü denetim baytları bir dize belirtecinin dışına çıkamaz. Şifreleme, PdfEncryptionWriter ve /Encrypt fragman girdisi aracılığıyla bağlanır. Açık anahtarlı şifreleme, sessizce atlanmak yerine açık bir özel durumla reddedilir. Deterministik ve yeniden üretilebilir saat kipleri, zaman damgası ve sıralama yan kanallarını çıktıdan kaldırır. Belge tehdit modeli ve şifreleme güven sınırı için /modules/core/security/ sayfasına bakın.

Uygunluk

Writer, PDF 2.0 dosya yapılarını üretir: %PDF-2.0 başlığı, bir /2.0 katalog sürümü, bir çapraz başvuru akışı ve ISO 32000-2 §7.3.4.2 kaçış tablosuna göre sabit dize kaçışı. Bunlar uygulamanın gerçek davranışlarıdır. Kanıtlar src/Writer/Pdf20StreamStrategy.php, src/Writer/PdfSerializationStrategy.php dosyalarında ve src/Writer/PdfWriter.php içindeki strateji seçiminde bulunur. Davranış, tests/Unit/Writer/ (Pdf20StreamStrategy, PdfXrefWriter ve Linearizer* paketleri dahil 192 test) ve tests/Golden/PdfWriter/PdfWriterGoldenBaselineSmokeTest taban çizgisi tarafından sınanır.

Bu, tam PDF 2.0 uygunluğu iddiası değildir. Tam ISO 32000-2 uygunluğu, yalnızca seri hâle getiricinin değil, harici bir oracle tarafından doğrulanan tam bir belgenin özelliğidir. Uçtan uca uygunluk yalnızca bir oracle onayladığında ileri sürülür: tests/Integration/Accessibility/VeraPdfUa2GoldenTest, oluşturulan bir test fikstürünü PDF/UA-2 için veraPDF’ye karşı doğrular ve tests/Standards/Profile/PdfRConformanceTest, PDF/R profilini kapsar. veraPDF golden testi, çalıştırıcıda veraPDF ikili dosyası yoksa atlanır, bu nedenle koşulsuz değil, isteğe bağlı bir oracle kapısıdır. Çalıştırmak için VERAPDF_BINARY değerini ayarlayın. Arşivsel profil seçimi (PDF/A-3 → PDF 1.7, PDF/A-4 → PDF 2.0) ADR-011 ve uygunluk kipi tarafından belirlenir ve /modules/core/conformance/ içindeki uygunluk paketleri tarafından doğrulanır. Bu oracle destekli profillerin dışında, niteliksiz uygunluk ileri sürmek yerine Writer’ın “PDF 2.0 yapıları ürettiğini; uygunluğun PDF/UA-2 profili için veraPDF tarafından doğrulandığını” belirtin.