TCPDF uyumluluğu için geliştirici kılavuzu

Bir bakışta

Uyumluluk bağdaştırıcısı bir geçiş katmanıdır. Eski davranışı gizlemek yerine görünür kılar. Yüksek değerli yolları yerel NextPDF API’lerine taşırken uygulamanızı çalışır durumda tutmak için bu katmanı kullanın.

TCPDF biçimli eski kodun bakımını yaptığınızda, bağdaştırıcı kapsamını genişlettiğinizde veya yerel NextPDF API’lerine aşamalı bir geçiş planladığınızda bu kılavuzu kullanın.

Mimari sınır

Katman	Sahibi	Sorumluluk	Buraya koymayın
Eski uygulama	Uygulama	Mevcut TCPDF biçimli çağrıları geçiş sırasında çalışır durumda tutar.	Yerel NextPDF API’lerini kullanması gereken yeni PDF özellikleri.
Bağdaştırıcı kabuğu	nextpdf/compat-legacy	Bu katman, TCPDF biçimli sınıfı ve paylaşılan uyumluluk durumunu dışa açar.	Büyük yöntem aileleri veya dönüştürme mantığı.
Concern trait’leri	nextpdf/compat-legacy	Eski yöntem ailelerini gruplar: metin, yazı tipleri, görseller, güvenlik, formlar, sayfalar.	Aileler arası çıktı ilkesi.
Köprü (bridge) sınıfları	nextpdf/compat-legacy	Eski bağımsız değişkenleri, hedefleri, renkleri, birimleri ve biçimleri dönüştürür.	İşletmeye özgü davranış.
Çekirdek motor	nextpdf/nextpdf	Yerel belgeyi oluşturur.	Eski uyumluluk vaatleri.

Çalışma zamanı yaşam döngüsü

Aşama	Davranış	Geliştirici eylemi
Önyükleme	İsteğe bağlı eski önyükleme, uyumluluk adlarını dışa açar.	Bunu yalnızca eski kodun TCPDF sembollerini beklediği yerlerde kullanın.
Kurulum (yapılandırıcı)	Bağdaştırıcı, eski yapılandırıcı bağımsız değişkenlerini çekirdek belge yapılandırmasına eşler.	Geçiş sırasında yapılandırıcı girdilerini kararlı tutun.
Yöntem çağrısı	Desteklenen yöntemler, concern’ler ve köprüler aracılığıyla NextPDF davranışına eşlenir.	Eşitlik (parity) varsaymadan önce yöntem kapsamını denetleyin.
Desteklenmeyen özellik	Bağdaştırıcı, desteklenmeyen davranış için açık uyumluluk istisnaları fırlatır.	Çağrıyı değiştirin veya uygulama kodunun arkasında yalıtın.
Çıktı	Çıktı köprüsü, eski hedef davranışını NextPDF çıktısına eşler.	Dosya adlarını ve depolama köklerini doğrulayın.

Geçiş envanteri

Uygulamanızdaki her TCPDF yöntem çağrısını toplayarak başlayın. Davranışı değiştirmeden önce her çağrıyı sınıflandırın.

Sınıflandırma	Anlamı	Eylem
Desteklenen bağdaştırıcı yöntemi	Yöntem destekleniyor olarak belgelenmiştir ve testleri vardır.	Geçici olarak koruyun; bu alana dokunduğunuzda geçiş yapın.
Kısmi bağdaştırıcı yöntemi	Yöntem mevcuttur, ancak davranışı eski TCPDF ile tam olarak eşleşmez.	Fixture testleri ekleyin ve çıktıyı el ile doğrulayın.
Açıkça desteklenmeyen yöntem	Bağdaştırıcı bir uyumluluk istisnası fırlatır.	Bunu yerel NextPDF ile değiştirin veya özelliği kaldırın.
İşletmeye özgü sarmalayıcı	Uygulama, TCPDF çağrılarını zaten sarmalar.	Önce sarmalayıcının iç bölümlerine geçiş yapın.
Uyumluluğa duyarlı çağrı	İmza, şifreleme, etiketleme, PDF/A, erişilebilirlik veya fatura akışı.	Özel doğrulamayla yerel NextPDF API’lerine geçiş yapın.

Bağdaştırıcıya katkı deseni

Uyumluluk desteğini, ilgili davranışı sahiplenen en küçük yöntem ailesine ekleyin.

Değişiklik türü	Nerede uygulanacağı	Gerekli test
Metin çıktısı yöntemi	Concerns\AdaptsTextOutput ya da yazı tipi concern’i.	Eski fixture ile birlikte yerel çıktı doğrulaması.
Sayfa veya kenar boşluğu yöntemi	Sayfa, konumlandırma veya kenar boşluğu concern’i.	Koordinat dönüşümü ve sayfa durumu testi.
Görsel veya çizim yöntemi	Görsel, çizim, renk veya gradyan concern’i.	Girdi doğrulaması ve visual/structural çıktı testi.
Çıktı hedefi	OutputBridge.	Hedef eşlemesi ve güvensiz yol testi.
Desteklenmeyen özellik	İstisna fabrikası ya da yöntem kapsamı tablosu.	İstisna türü ve ileti testi.

Bir concern trait’i bir yöntem ailesini sahiplendiğinde, büyük bir yöntemi doğrudan bağdaştırıcı kabuğuna koymayın.

Yerel geçiş deseni

Eski kodu kararlı hale getirmek için bağdaştırıcıyı kullanın, ardından kararlı iş akışlarını yerel API’lere taşıyın.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

Geçişi, küçük davranışsal adımlardan oluşan bir dizi olarak ele alın. Yüksek riskli bir bölüm yerel API’lere taşınırken bir sayfa hâlâ bağdaştırıcıyı kullanabilir.

Genişletme noktaları

Genişletme noktası	Şunun için kullanın	Kısıt
AdaptationConfig	Geçiş sırasında bağdaştırıcı davranışını denetler.	Varsayılanları açık ve gözden geçirilmiş tutun.
Concern trait’leri	Metin, formlar, görseller veya güvenlik gibi yöntem ailelerini gruplar.	Yöntemleri bağdaştırıcı kabuğuna değil, uygun concern’e ekleyin.
Köprü (bridge) sınıfları	Eski bağımsız değişken biçimlerini çekirdek değerlere dönüştürür.	Köprü davranışını geçiş testleriyle kapsayın.
CompatAdapterInterface	Araçlar için bağdaştırıcı düzeyinde soyutlama.	Yeni kodda yerel çekirdek sözleşmelerinin yerine kullanmayın.
Yöntem kapsamı tablosu	Geliştiriciye yönelik destek kaydı.	Destek durumu değiştiğinde tabloyu güncelleyin.

Geçiş iş akışı

1. Bağdaştırıcıyı kurun ve eski test paketini değiştirmeden çalıştırın.
2. Ardından Yöntem kapsamı sayfasını açın ve çağrılan her yöntemi sınıflandırın.
3. Önce desteklenmeyen yöntemleri değiştirin.
4. Yüksek hacimli veya uyumluluğa duyarlı yolları yerel çekirdek API’lerine taşıyın.
5. Geçiş yapılan her yöntem ailesi için fixture kapsamı ekleyin.
6. Artık hiçbir uygulama giriş noktası bunlara bağımlı olmadığında önyükleme takma adlarını kaldırın.

Hata işleme

Hata	Nerede işlenmeli	Önerilen yanıt
Desteklenmeyen yöntem	Bağdaştırıcı istisnası.	Çağrıyı değiştirin veya bir uygulama bağdaştırıcısının arkasında yalıtın.
Kısmi yerleşim eşitliği	Geçiş testleri ve görsel inceleme.	Yayına almadan önce kabul edilen farkı belgeleyin.
Güvensiz çıktı hedefi	OutputBridge ve uygulama depolama ilkesi.	Güvensiz yolları reddedin ve yerel çıktı API’lerini tercih edin.
Güvenlik özelliği uyuşmazlığı	Yerel geçiş planı.	Düzenlemeye tabi çıktılar için yalnızca uyumluluğa dayalı davranışı yayına almayın.
Önyükleme takma adı çakışması	Uygulama önyüklemesi.	Genel takma adları kaldırın veya bunları eski giriş noktalarıyla sınırlayın.

Güvenli varsayılanlar

Concern	Varsayılan	Ne zaman geçersiz kılınmalı
Desteklenmeyen yöntemler	Açık istisna fırlatır.	Bunu üretimde zayıflatmayın.
Eski varsayılanlar	Varsayılanlar LegacyDefaults içinde merkezileştirilmiştir.	Yalnızca bilinen geçiş davranışı için geçersiz kılın.
Çıktı eşlemesi	Çıktı, OutputBridge üzerinden geçer.	Geçişten sonra yerel çıktı API’lerini kullanın.
Kapsam kaynağı	Yöntem kapsamı sayfası ve testleri.	Her bağdaştırıcı yükseltmesinden sonra kapsam denetimlerini yeniden çalıştırın.
Katı kip	Geçiş denetimleri sırasında etkin tutun.	Yalnızca belgelenmiş bir eski uyumluluk penceresi için devre dışı bırakın.

Test kontrol listesi

• Geçiş yapılan her yöntem ailesi için eski bir fixture’ı koruyun.
• Eski bir yöntemi değiştirmeden önce yerel bir NextPDF testi ekleyin.
• Desteklenmeyen yöntemlerin belgelenmiş istisnayı fırlattığını doğrulayın.
• Tam bayt eşitliği gerçekçi bir geçiş hedefi olmadığında çıktı yapısını karşılaştırın.
• Bağdaştırıcı yöntemleri ekledikten veya değiştirdikten sonra yöntem kapsamı denetimlerini çalıştırın.
• Eski kodun kullandığı her çıktı hedefi için depolama yolu testleri ekleyin.