Backport Builder API başvurusu

Bir bakışta

Backport Builder, çalışma zamanı kütüphanesi değil, derleme araçlarından oluşan bir kümedir. Genel arabirimini şu öğeler oluşturur: derleme komut kümesi (scripts/build.php ve onun composer build* sarmalayıcıları), bunların arkasındaki dört betik düzeyli sınıf (Build, MergeSources, AdjustComposer, ValidateBuildContract), üç Rector yapılandırma dosyası, üç özel Rector kuralı ve oluşturulan paket sözleşmesi (nextpdf/backport ve nextpdf/backport-pro). Güncel NextPDF kaynağını sürümü düşürülmüş bir dağıtıma dönüştürmek için bu aracı bir derleme veya sürekli tümleştirme (CI) ana makinesinde çalıştırın. Bunu hiçbir zaman uygulamanıza eklemeyin.

Yeni başlıyorsanız composer build:dry ile başlayın (bu, php scripts/build.php --dry-run komutuna karşılık gelir). Bu, dosya yazmadan her aşamayı yalnızca raporlama kipinde çalıştırır; böylece gerçek bir derlemeden önce kaynak yerleşimini ve bayrakları doğrulayabilirsiniz. İlk “Yaygın görevler” örneği aynı komutu gösterir.

Yaygın görevler

Bu paketi çoğunlukla derlemeleri bir derleme ana makinesinde çalıştırmak için kullanırsınız. Aşağıdaki her örnek, scripts/build.php ve composer.json dosyalarına karşı doğrulanmış tek bir komuttur.

İşlem hattını hiçbir şey yazmadan doğrulayın (güvenli ilk çalıştırma):

composer build:dry

Bu, php scripts/build.php --dry-run komutuna karşılık gelir. Birleştirme, Rector, composer oluşturma, varlık kopyalama ve doğrulama adımlarını yalnızca raporlama kipinde çalıştırır ve hiçbir şey kopyalamaz.

Tam PHP 8.1 dağıtımını üretin (nextpdf/backport ve Pro kaynağı mevcut olduğunda ayrıca nextpdf/backport-pro):

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

Bu, çekirdeği, çerçeve bağdaştırıcılarını ve tcpdf uyumluluk katmanını birleştirir. PHP 8.1 hedefi için tek bir Rector geçişi çalıştırır ve oluşturulan paket ağacını ./output dizinine yazar. Pro paketini atlamak için --no-pro ekleyin.

Yalnızca çekirdek PHP 7.4 dağıtımını üretin (iki geçişli enum işlem hattı):

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

--target=php74, yalnızca çekirdek çıktıyı zorunlu kılar, Pro’yu devre dışı bırakır ve enum ön işleme, Rector sonrası düzeltmeler ve tam PHP 7.4 sürüm düşürme geçişini çalıştırır.

Komut yüzeyleri

Derleme giriş noktaları ve derlemeyi yürüten betik düzeyli sınıflar için tam imzalar, bayraklar ve çıkış davranışı gerektiğinde bu tabloyu kullanın.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumlarda hata verir veya başarısız olur	Notlar
scripts/build.php	Betiğin belgelediği hedef, sürüm, kaynak yolları, çıktı yolları ve bayraklar.	Dala özgü hedef varsayılanlarını kullanır.	Oluşturulan paket ağacı.	Sıfır olmayan çıkış kodu ve aşamaya özgü hata çıktısı.	Ana derleme giriş noktası. Bir uygulamada değil, bir derleme ana makinesinde çalıştırın.
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false)	Sürüm, kaynak dizini, çıktı dizini, hedef çalışma zamanı şeridi, Pro dahil etme bayrağı, kuru çalıştırma bayrağı.	PHP 8.1’i hedefler, PHP 7.4 dışında Pro’yu dahil eder ve kuru çalıştırma etkin olmadıkça yazar.	Build	InvalidArgumentException (desteklenmeyen hedef için); run() sırasında aşama hataları.	Betik düzeyli sınıf, scripts/build.php arkasında yer alır.
Build::run()	yok.	Sözleşmeyi doğrular, kaynakları birleştirir, composer.json meta verisini ayarlar ve Rector geçişlerini çalıştırır.	bool	Beklenen aşama hataları için false döndürür; beklenmeyen dosya sistemi veya çalışma zamanı hataları için hata fırlatabilir.	CI, false durumunda başarısız olmalıdır.
composer build:dry	Composer betik sarmalayıcısı.	Kuru çalıştırma ile derleme doğrulaması.	Çıkış durumu ve günlükler.	Derleme veya doğrulama hatasında sıfır olmayan çıkış.	CI geçitleri tarafından kullanılır.
scripts/merge-sources.php	Kaynak checkout yolları ve birleştirme hedefi.	Hedef çalışma zamanı için seçili kaynak paketlerini birleştirir.	Birleştirilmiş kaynak ağacı.	Eksik kaynak, desteklenmeyen hedef, dosya sistemi hatası.	Kaynak başvurularını sürüm etiketiyle hizalı tutun.
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false)	Kaynak temel dizini, çıktı dizini, Pro dahil etme bayrağı, kuru çalıştırma bayrağı, yalnızca çekirdek bayrağı.	Yapılandırılmış tüm depoları birleştirir; coreOnly doğru olduğunda yalnızca çekirdeği birleştirir.	MergeSources	Çalıştırma sırasında geçersiz kaynak veya çıktı yolları.	Betik düzeyli sınıf, scripts/merge-sources.php arkasında yer alır.
MergeSources::run()	yok.	Seçili kaynak ağaçlarını derleme hedefine kopyalar ve normalleştirir.	bool	Beklenen birleştirme hataları için false döndürür.	Günlükler getLog() ile okunabilir.
MergeSources::getLog()	yok.	Birikmiş aşama günlüğü girdilerini döndürür.	array	beklenmez.	CI tanılaması için kullanın.
scripts/adjust-composer.php	Oluşturulan composer.json meta verisi ve sürümü.	Oluşturulan çıktı için paket kısıtlamalarını ve değiştirme (replace) girdilerini yazar.	Ayarlanmış composer.json.	Geçersiz sürüm veya eksik oluşturulmuş dosyalar.	Oluşturulan paket kimliğinden sorumludur.
AdjustComposer::__construct(string $version, string $target = 'php81')	Sürüm dizesi ve hedef şerit.	PHP 8.1 hedefi.	AdjustComposer	Oluşturma yollarında geçersiz hedef hataları.	Derleme betikleri ve testler tarafından kullanılır.
AdjustComposer::generatePublicComposer()	yok.	Şu paket için meta veri üretir: nextpdf/backport.	array	beklenmez.	Testler için yan etkisiz oluşturma API’si.
AdjustComposer::generateProComposer()	yok.	Şu paket için meta veri üretir: nextpdf/backport-pro.	array	beklenmez.	Tescilli derleme şeridi için yan etkisiz oluşturma API’si.
AdjustComposer::writePublicComposer(string $outputDir)	Çıktı dizini.	Oluşturulan genel composer.json dosyasını yazar.	void	Dosya sistemi hataları.	Yalnızca oluşturulan çıktı dizinlerinde kullanın.
AdjustComposer::writeProComposer(string $proOutputDir)	Pro çıktı dizini.	Oluşturulan Pro composer.json dosyasını yazar.	void	Dosya sistemi hataları.	Pro çıktı ağacının var olmasını gerektirir.
ValidateBuildContract::__construct(string $repoRoot)	Depo kökü.	Sağlanan depo kökünü sözleşme temeli olarak kullanır.	ValidateBuildContract	beklenmez.	Betik düzeyli sözleşme doğrulayıcısı.
ValidateBuildContract::run()	yok.	Gerekli girdileri ve derleme varsayımlarını denetler.	bool	Sözleşme hatasında false döndürür.	Derleme çıktısına güvenilmeden önce çalıştırın.

Rector yapılandırması

Hangi Rector yapılandırma dosyasının her hedef şeridi yönettiğini ve her geçişin PHP 8.1 tek geçişli veya PHP 7.4 iki geçişli işlem hattında nerede yer aldığını görmek için bu tabloyu kullanın.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumlarda hata verir veya başarısız olur	Notlar
rector/config/rector-php81.php	Kaynak ağacı ve Rector çalışma zamanı.	PHP 8.1 hedefi için tek geçişli sürüm düşürme.	Dönüştürülmüş kaynak.	Rector ayrıştırma veya dönüştürme hatası.	PHP 8.1 dağıtım şeridi için kullanılır.
rector/config/rector-php74-enums.php	Kaynak ağacı ve Rector çalışma zamanı.	Enum dönüşümü için ilk PHP 7.4 geçişi.	Ara dönüştürülmüş kaynak.	Rector ayrıştırma veya dönüştürme hatası.	Tam PHP 7.4 geçişinden önce çalışır.
rector/config/rector-php74.php	Ara kaynak ve Rector çalışma zamanı.	Tam PHP 7.4 sürüm düşürme geçişi.	PHP 7.4 uyumlu kaynak.	Rector ayrıştırma veya dönüştürme hatası.	PHP 7.4 dağıtım şeridi için kullanılır.

Özel kurallar

Üç projeye özgü Rector kuralını sürdürdüğünüzde veya genişlettiğinizde ve her kuralın yöntem sözleşmesine ve dönüştürdüğü söz dizimine ihtiyaç duyduğunuzda bu tabloyu kullanın.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumlarda hata verir veya başarısız olur	Notlar
DowngradeAsymmetricVisibilityRector	Asimetrik görünürlük kullanan özellikler veya yükseltilmiş parametreler.	Eski çalışma zamanlarıyla uyumlu düz görünürlük.	Mümkün olduğunda okuma görünürlüğünü korur.	Rector kuralı hatası.	Ayarlayıcı (setter) kısıtlamaları yalnızca derleme zamanında geçerlidir ve oluşturulan çıktıda kaldırılır.
DowngradeAsymmetricVisibilityRector::getRuleDefinition()	yok.	Rector kuralı meta verisini ve örneklerini döndürür.	RuleDefinition	beklenmez.	Kural belgelerini Rector araçlarına görünür tutar.
DowngradeAsymmetricVisibilityRector::getNodeTypes()	yok.	Kuralın incelediği düğüm türlerini seçer.	array<class-string<Node>>	beklenmez.	Belirlenimci dönüşümler için kapsam dar kalmalıdır.
DowngradeAsymmetricVisibilityRector::refactor(Node $node)	AST düğümü.	Varsa asimetrik görünürlüğü dönüştürür.	`Node	null`	Rector kuralı hatası.
DowngradeCloneWithRector	clone() ile özellik geçersiz kılmaları.	Klonlama ve açık özellik atamaları.	Oluşturulan geçici değişkenleri kullanır.	Rector kuralı hatası.	Salt okunur özellik sürüm düşürmelerinden sonra çalışmalıdır.
DowngradeCloneWithRector::getRuleDefinition()	yok.	Kural meta verisini ve örneklerini döndürür.	RuleDefinition	beklenmez.	Rector tanılaması tarafından kullanılır.
DowngradeCloneWithRector::getNodeTypes()	yok.	Dönüş ve ifade düğümlerini seçer.	array<class-string<Node>>	beklenmez.	Kuralı clone-with söz dizimine odaklı tutar.
DowngradeCloneWithRector::refactor(Node $node)	AST düğümü.	clone-with ifadesini klonlama ve atamalar olarak yeniden yazar.	`array	null`	Rector kuralı hatası.
DowngradeTraitConstantsRector	Trait sabitleri ve bunlara yapılan başvurular.	Statik özellikler ve özellik başvuruları.	Mümkün olduğunda görünürlüğü korur.	Rector kuralı hatası.	Eski çalışma zamanlarında özellikler final olamayacağı için final öğesini kaldırır.
DowngradeTraitConstantsRector::getRuleDefinition()	yok.	Kural meta verisini ve örneklerini döndürür.	RuleDefinition	beklenmez.	Rector tanılaması tarafından kullanılır.
DowngradeTraitConstantsRector::getNodeTypes()	yok.	Trait ve sınıf sabiti getirme düğümlerini seçer.	array<class-string<Node>>	beklenmez.	Kuralı trait sabitleriyle sınırlı tutar.
DowngradeTraitConstantsRector::refactor(Node $node)	AST düğümü.	Trait sabitlerini ve başvurularını uyumlu özelliklere yeniden yazar.	`Node	null`	Rector kuralı hatası.

Oluşturulan paket sözleşmesi

Derleyicinin ne ürettiğini görmek için bu tabloyu kullanın: aşağı akış projelerinin yüklediği paket adları ve Pro dağıtımını taşıyan paket.

Üretilen paket	Çalışma zamanı rolü	Notlar
nextpdf/backport	Oluşturulan açık kaynaklı çalışma zamanı dağıtımı.	Hedef çalışma zamanı için seçili nextpdf/* paketlerini değiştirir.
nextpdf/backport-pro	Pro kaynağı mevcut olduğunda oluşturulan tescilli Pro dağıtımı.	Açık kaynaklı paketten ayrı olarak yayımlanır.

Geliştirme notları

• Derleyici, kaynak sürümlerini tüketir ve oluşturulmuş yapıtlar üretir. Oluşturulan çıktı üzerinde doğruluk kaynağıymış gibi yama yapmayın.
• Her özel kuralın, derleme işlem hattına girmeden önce fikstür testleri olmalıdır.
• Sürüm işleri, oluşturulan çıktıyı yalnızca derleme ana makinesinde değil, hedef çalışma zamanında doğrulamalıdır.