Eski kitaplıklardan geçiş: TCPDF, FPDF ve benzerleri

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

Bir bakışta

PDF’leriniz TCPDF, FPDF, mPDF ya da dompdf tarafından üretiliyorsa, kod büyük olasılıkla hâlâ çalışıyordur. Sorunun gözden kaçmasının kolay olmasının nedeni de tam olarak budur. Kitaplık çalışır, dosya açılır ve boşluk yalnızca biri imzalı, arşivlenebilir ya da erişilebilir bir belge istediğinde ve yanıt “buradan yapamayız” olduğunda ortaya çıkar.

Bu sayfa geçiş hikâyesidir: o duvarların ne olduğu, neden tesadüfi değil yapısal oldukları ve NextPDF’in onlardan aşamalı bir yol sunarak nasıl bir çıkış sağladığı — bayt birebir bir doğrudan değiştirme vaadi değil, bir geçiş yardımı olan bir TCPDF uyumluluk yüzeyi de dahil.

Bunun önemi nedir

Bir PDF kitaplığı, bir kez yaptığınız bir işleme çağrısı değildir. Belgelerinizin var oldukları sürece miras aldığı bir bağımlılıktır. O bağımlılık ilerlemeyi durdurduğunda, belgeleriniz de yeni şeyler yapabilme yeteneğini yitirir — ve bunu en kötü zamanda, bir müşteri, bir denetçi ya da bir düzenleyici çıtayı belirlediğinde öğrenirsiniz.

Duvarlar şuna benzer. Biçim ilerledi: PDF 2.0, standardın güncel sürümüdür (SpecSpec: ISO 32000-2ISO 32000-2) ve 1.x yapısında takılı kalmış bir yazıcı, araç zincirinizin geri kalanının varsaydığı biçimin gerisindedir. İmzalama incedir ya da sonradan eklenmiştir; bir imzanın geçerliliğini koruyabilmesini sağlayan PAdES taban profillerinin epey gerisinde (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). PDF/A ailesine arşivsel çıktı ve erişilebilirlik için etiketli yapı, ya eksiktir ya da kırılgandır. API’nin kendisi de türsüzdür — dizge yönelimleri, konumsal mantıksal değerler, kazara keşfettiğiniz varsayılanlar — bu yüzden derleyici de bir gözden geçiren de size yardım edemez.

Bunların hiçbiri çevresinden dolaşıp yamayabileceğiniz hatalar değildir. Bunlar, önceki bir on yıl için kurulmuş bir aracın biçimidir ve o araçların birkaçı, belgelerinizin artık karşılaması gereken standartlara doğru artık etkin biçimde ilerlemiyor.

Kısa özet

• Eski PHP PDF kitaplıkları çoğunlukla hâlâ çalışır. Sorun, tam modern uygunlukla genellikle üretemedikleri şeydir: PDF 2.0, taban düzeyine uygun imzalar, doğrulanmış PDF/A, etiketli erişilebilirlik — adı geçen kitaplıklar genelinde destek sınırlıdır ya da yoktur.
• NextPDF, varsayılan olarak PDF 2.0 yazan bir PHP 8.4 motorudur; katı türleri, arşivsel profilleri ve birinci sınıf çıktılar olarak PAdES imzalamayı sunar.
• İlk günde her şeyi yeniden yazmak zorunda değilsiniz. TCPDF uyumluluk yüzeyi, önemli olan belge mantığını taşırken tanıdık çağrıların çalışmaya devam etmesini sağlar.
• O yüzey, TCPDF ile bayt birebir değil, uyumludur. Belgelenmiş davranışsal farklarla birlikte geçişi köprüleyen bir köprüdür — her betiğin değişmeden çalıştığı iddiası değil.
• Dürüst sınav, yeni yeteneklerin bu hamleye değip değmediğidir. Bazı iş yükleri için değmez ve bunu açıkça söyleriz.

NextPDF bu işe nasıl yaklaşır

Yaklaşım, geçişi bir sıçrama değil, bir dizi adım hâline getirmektir. Yol boyunca belge üretmeyi sürdürürsünüz ve bir bütün-bir-anda yeniden yazma üzerine bir sürümü riske atmak yerine eski kısıtları teker teker takas edersiniz.

1. InventoryCatalogue what your documents actually need to emit — signatures, archival profiles, tagged structure, fonts — not just which calls you make today.
2. BridgeAdopt the TCPDF-compatibility surface so the existing call sites keep producing files while the engine underneath becomes NextPDF.
3. PortMove the document logic that matters onto the native typed API, where intent is explicit and the compiler checks it.
4. UpgradeTurn on the outputs many legacy libraries cannot reach with full modern conformance: PDF 2.0 structure, validated PDF/A, PAdES signatures, tagged accessibility.
5. VerifyConfirm the result against a real validator, so 'archival' or 'signed' means a tool agrees, not just that the file opened.

A staged migration off a legacy PDF library: start on the compatibility surface so existing calls keep working, then move document logic onto the typed native API, then turn on the standards-grade outputs (PDF 2.0, PDF/A, PAdES, accessibility) that many legacy libraries cannot produce with full modern conformance.

PDF 2.0 taban düzeyidir, bir özellik bayrağı değil. NextPDF, biçimin güncel sürümünü varsayılan olarak yazar (SpecSpec: ISO 32000-2ISO 32000-2) ve bir profil istediğinde eski yapıları serileştirebilir. 1.x yapısında donmuş bir kitaplık burada size erişemez; bu, eksik kaldığı bir ayar değildir, öncesinde var olduğu bir çağdır.

Arşivleme ve erişilebilirlik birer yazıcı özelliğidir. Bir doğrulayıcının PDF/A olarak kabul ettiği bir dosya üretmek, motorun yazarken yapması gereken bir şeydir — sonradan iliştirilemez (SpecSpec: ISO 19005-4ISO 19005-4). Bir PDF’yi erişilebilir kılan etiketli yapı için de aynısı geçerlidir. NextPDF bunları üretim sırasında kurar; ki bu tam olarak birçok eski aracın atamadığı — ya da yalnızca kısmen, bir doğrulayıcının kabul ettiğinin gerisinde attığı — adımdır.

İmzalama taban düzeyi çıtasını aşar. Bir PDF’deki gelişmiş elektronik imzalar PAdES profillerini izler (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4); burada özet, bildirilmiş bir bayt aralığını kapsar ve imza, bir doğrulayıcının denetlediği üst veriyi taşır. Sonradan eklenmiş bir imzalama yardımcısı bu çıtaya nadiren ulaşır. NextPDF bunu sonradan akla gelen bir ek değil, birinci sınıf bir çıktı olarak ele alır.

Uyumluluk yüzeyi köprüdür, dürüstçe ifade edilmiş. TCPDF-compat katmanı, var olan çağrı noktalarınız önemli kısımları taşırken belge üretmeyi sürdürsün diye vardır. Her NextPDF geçiş kılavuzuyla aynı modeli izler: kaynak kitaplıkla uyumlu, bayt birebir değil, davranışsal farklar yazılı. O dürüstlük asıl noktadır — sessiz bir “%99 doğrudan değiştirme” iddiası, bu motorun reddetmek üzere kurulduğu türden bir tahmindir.

Human-factors note:Human-factors note

Geçiş nedeni nadiren bugün elinizdeki koddur; yarın sizden istenecek belgedir. Sürdürülebilirlik, adı konmuş bir kalite özelliğidir — ihtiyaçlar değiştikçe bir sistemin ne kadar kolay çözümlenip değiştirilebildiği (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). İlerlemeyi durdurmuş bir bağımlılık onu sessizce aşındırır ve bedeli yalnızca yeni bir gereksinim geldiğinde ve yanıtın “buradan değil” olmak zorunda kaldığında hissedersiniz. Aşamalı bir hamle, belgeler akmaya devam ederken bu bedeli son tarih baskısı altında bir anda değil, sizin takviminizde öder.

Pratik örnek

Bir geçişin biçimi çağrı noktasında küçüktür. Eski kod, uyumluluk yüzeyi aracılığıyla bir dosya üretmeyi sürdürür; yeni kod, niyeti türlü yerel API üzerinden bildirir ve eski kitaplığın ulaşamadığı ya da yalnızca sınırlı uygunlukla ulaştığı bir çıktıyı ister.

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

İlk blok, dayanağınızdır: belgelerin akmaya devam etmesi için uygulamanızda hiçbir şeyin değişmesi gerekmez. İkincisi, hedeftir: “dikey”, “dizge çıktısı” ve fontun açık olduğu ve arşivleme, imzalama ile erişilebilirliğin tosladığınız duvarlar değil, açabileceğiniz çıktılar hâline geldiği türlü bir çağrı.

Yaygın yanlış anlama

Sık rastlanan umut, “eski kitaplığıma PDF 2.0 ve imza yaptıracak bir bayrak olmalı”dır. Yoktur. Bunlar, olgun bir kitaplığın açığa çıkarmayı unuttuğu seçenekler değildir; mimarisinin hiçbir zaman üzerine kurulmadığı yeteneklerdir. Bir yazıcının uygulamadığı bir biçim sürümüne ya da bir imza profiline yapılandırma yoluyla varamazsınız.

Bunun ayna görüntüsü yanlış anlama, NextPDF’in %100 bir TCPDF doğrudan değiştirmesi olduğu ve dolayısıyla geçişin bedavaya geldiğidir. Değildir ve bunun aksiymiş gibi davranmayacağız. Uyumluluk yüzeyi, sizi bu hamlede taşımak için API’nin gerçek, belgelenmiş bir dilimini kapsar; bazı çağrılar farklı davranır ve birkaçı kapsam dışıdır. Onu, her eski betiğin dokunulmadan çalıştığının garantisi değil, yayımlanmış bir haritası olan bir köprü olarak ele alın.

Sınırlar ve kapsam

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ Uyumluluk yüzeyi, TCPDF ile bayt birebir değil, uyumludur. Geçiş sırasında var olan çağrı noktalarının dosya üretmeyi sürdürmesi için API’nin belgelenmiş bir alt kümesini kapsar. Bir doğrudan değiştirme değil, bir köprüdür: bazı davranışlar farklılaşır ve bazı çağrılar desteklenmez; tümü yöntem-kapsamı ve geçiş sayfalarında listelenir. Hedef, standart düzeyindeki çıktının yaşadığı yerel türlü API’dir.
Pro	●Available
Enterprise	●Available

Geçiş bir araçtır, bir erdem değil. Belgeleriniz basitse, kitaplığınız hâlâ bakımdaysa ve PDF 2.0’a, imzalamaya, PDF/A’ya ya da erişilebilirliğe hiçbir zaman ihtiyaç duymayacaksanız, dürüst yanıt olduğunuz yerde kalmak olabilir — geçiş maliyeti gerçektir ve ihtiyaç duymadığınız bir hamle, yapmamanız gereken bir hamledir. NextPDF ne zaman kullanılmamalı sayfası bu çizgiyi gözünü kırpmadan çizer.

Bu sayfa geçiş yolunu ve motorun hedeflerini anlatır. Tam API kapsamı, davranışsal farklar ve adım adım yordam, her çağrının ne yaptığı konusunda yetkili olan uyumluluk belgelerinde yer alır. Buradaki hiçbir şey, keyfi bir eski betiğin değişmeden çalışacağını vaat etmez.

İlgili belgeler

• PDF 2.0 neyi değiştirdi — birçok eski kitaplığın üretemediği biçim sürümü ve neden önemli olduğu.
• TCPDF uyumluluk yüzeyi — köprünün neyi kapsadığı ve nerede farklılaştığı konusunda yetkili kılavuz.
• NextPDF ne zaman kullanılmamalı — dürüst sınır; böylece ihtiyaç duymadığınız bir geçişi atlayabilirsiniz.
• Tek motor, her çerçeve — geçtiğiniz motorun, hâlihazırda çalıştırdığınız yığına nereye takıldığı.

Sözlük

• PDF 2.0 — Taşınabilir Belge Biçimi standardının güncel sürümü (ISO 32000-2). İlk kullanımda genişletilir; NextPDF’in varsayılan olarak yazdığı biçim.
• PDF/A — bir PDF’yi uzun vadede saklamayı güvenli kılan şeyi tanımlayan arşivsel uygunluk ailesi (ISO 19005 serisi). Yazıcının üretmesi gereken bir özelliktir, bir çağıranın sonradan ekleyebileceği bir şey değil.
• PAdES — PDF Advanced Electronic Signatures; bir PDF’ye standart düzeyindeki imzaları gömmek için ETSI profil ailesi (EN 319 142). İlk kullanımda genişletilir; imzalama sayfalarında ayrıntılı olarak ele alınır.
• Uyumluluk yüzeyi — bir kaynak kitaplığa (burada TCPDF) benzer biçimlendirilmiş ve var olan çağrı noktalarının geçiş sırasında çalışmaya devam etmesini sağlayan bir API katmanı. Özgünüyle bayt birebir değil, uyumludur — bir doğrudan değiştirme değil, bir köprü.
• Doğrudan değiştirme — var olan kodu değiştirmeden çalıştıran bir yerine geçen. TCPDF-compat yüzeyi bilinçli olarak bu şekilde tanımlanmaz; bilinen davranışsal farklara sahip belgelenmiş bir geçiş yardımıdır.