Referensi API Backport Builder
Sekilas
Bagian berjudul “Sekilas”Backport Builder adalah alat build, bukan pustaka runtime. Antarmuka publiknya terdiri dari kumpulan perintah build (scripts/build.php dan pembungkus composer build*-nya), empat kelas tingkat skrip yang mendasarinya (Build, MergeSources, AdjustComposer, ValidateBuildContract), tiga berkas konfigurasi Rector, tiga aturan Rector kustom, dan kontrak paket yang dihasilkan (nextpdf/backport dan nextpdf/backport-pro). Jalankan pada host build atau continuous integration (CI) untuk mengubah sumber NextPDF modern menjadi distribusi yang diturunkan versinya. Jangan pernah menambahkannya ke aplikasi.
Jika Anda baru memulai, gunakan composer build:dry terlebih dahulu (yang diterjemahkan menjadi php scripts/build.php --dry-run). Perintah ini menjalankan setiap tahap dalam mode hanya-laporan tanpa menulis berkas, sehingga Anda dapat memastikan tata letak sumber dan flag sebelum menjalankan build sebenarnya. Contoh pertama di bagian “Tugas umum” menunjukkan perintah yang sama.
Tugas umum
Bagian berjudul “Tugas umum”Anda akan paling sering menggunakan paket ini untuk menjalankan build pada host build. Setiap contoh di bawah ini merupakan satu perintah tunggal yang diverifikasi terhadap scripts/build.php dan composer.json.
Validasi alur (pipeline) tanpa menulis apa pun (langkah awal yang aman):
composer build:dryPerintah ini diterjemahkan menjadi php scripts/build.php --dry-run. Perintah ini menjalankan merge, Rector, pembuatan composer, penyalinan aset, dan validasi dalam mode hanya-laporan, serta tidak menyalin apa pun.
Hasilkan distribusi PHP 8.1 lengkap (nextpdf/backport, ditambah nextpdf/backport-pro bila sumber Pro tersedia):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./outputPerintah ini menggabungkan inti (core), adaptor framework, dan lapisan kompatibilitas tcpdf. Perintah ini menjalankan satu lintasan Rector untuk target PHP 8.1 dan menulis pohon paket yang dihasilkan ke ./output. Tambahkan --no-pro untuk melewati paket Pro.
Hasilkan distribusi PHP 7.4 khusus inti (pipeline enum dua-lintasan):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./output-php74 \ --target=php74--target=php74 memaksa keluaran khusus inti, menonaktifkan Pro, dan menjalankan pra-pemrosesan enum, perbaikan pasca-Rector, serta lintasan penurunan versi PHP 7.4 penuh.
Permukaan perintah
Bagian berjudul “Permukaan perintah”Gunakan tabel ini ketika Anda memerlukan tanda tangan, flag, dan perilaku keluar yang tepat untuk entrypoint build serta kelas tingkat skrip yang menjalankan build.
| Simbol | Parameter | Perilaku standar | Mengembalikan | Melempar atau gagal dengan | Catatan |
|---|---|---|---|---|---|
scripts/build.php | Target, versi, path sumber, path keluaran, dan flag sebagaimana didokumentasikan oleh skrip. | Menggunakan default target khusus per-branch. | Pohon paket yang dihasilkan. | Status keluar non-nol dan keluaran galat khusus tahap. | Entrypoint build utama. Jalankan pada host build, bukan di dalam aplikasi. |
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false) | Versi, direktori sumber, direktori keluaran, jalur runtime target, flag penyertaan Pro, flag dry-run. | Menargetkan PHP 8.1, menyertakan Pro kecuali untuk PHP 7.4, dan menulis kecuali jika dry-run diaktifkan. | Build | InvalidArgumentException untuk target yang tidak didukung; galat tahap selama run(). | Kelas tingkat skrip di balik scripts/build.php. |
Build::run() | tidak ada. | Memvalidasi kontrak, menggabungkan sumber, menyesuaikan metadata composer.json, dan menjalankan lintasan Rector. | bool | Mengembalikan false untuk kegagalan tahap yang diharapkan; dapat melempar galat untuk kesalahan sistem berkas atau runtime yang tidak terduga. | CI harus gagal ketika menerima false. |
composer build:dry | Pembungkus skrip Composer. | Validasi build dalam mode dry-run. | Status keluar dan log. | Keluar non-nol pada kegagalan build atau validasi. | Digunakan oleh gerbang CI. |
scripts/merge-sources.php | Path checkout sumber dan target merge. | Menggabungkan paket sumber yang dipilih untuk runtime target. | Pohon sumber yang digabungkan. | Sumber tidak ada, target tidak didukung, kegagalan sistem berkas. | Jaga agar referensi sumber tetap selaras dengan tag rilis. |
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false) | Direktori dasar sumber, direktori keluaran, flag penyertaan Pro, flag dry-run, flag khusus inti. | Menggabungkan semua repositori yang dikonfigurasi, atau hanya inti ketika coreOnly bernilai true. | MergeSources | Path sumber atau keluaran tidak valid saat proses berjalan. | Kelas tingkat skrip di balik scripts/merge-sources.php. |
MergeSources::run() | tidak ada. | Menyalin dan menormalkan pohon sumber yang dipilih ke dalam target build. | bool | Mengembalikan false untuk kegagalan merge yang diharapkan. | Log dapat dibaca dengan getLog(). |
MergeSources::getLog() | tidak ada. | Mengembalikan entri log tahap yang telah terakumulasi. | array | tidak ada yang diharapkan. | Gunakan untuk diagnostik CI. |
scripts/adjust-composer.php | Metadata dan versi composer.json yang dihasilkan. | Menulis batasan paket dan entri replace untuk keluaran yang dihasilkan. | composer.json yang disesuaikan. | Versi tidak valid atau berkas yang dihasilkan tidak ada. | Mengendalikan identitas paket yang dihasilkan. |
AdjustComposer::__construct(string $version, string $target = 'php81') | String versi dan jalur target. | Target PHP 8.1. | AdjustComposer | Galat target tidak valid pada path pembuatan. | Digunakan oleh skrip build dan pengujian. |
AdjustComposer::generatePublicComposer() | tidak ada. | Menghasilkan metadata untuk nextpdf/backport. | array | tidak ada yang diharapkan. | API pembuatan murni untuk pengujian. |
AdjustComposer::generateProComposer() | tidak ada. | Menghasilkan metadata untuk nextpdf/backport-pro. | array | tidak ada yang diharapkan. | API pembuatan murni untuk jalur build proprietary. |
AdjustComposer::writePublicComposer(string $outputDir) | Direktori keluaran. | Menulis composer.json publik yang dihasilkan. | void | Galat sistem berkas. | Gunakan hanya di dalam direktori keluaran yang dihasilkan. |
AdjustComposer::writeProComposer(string $proOutputDir) | Direktori keluaran Pro. | Menulis composer.json Pro yang dihasilkan. | void | Galat sistem berkas. | Membutuhkan pohon keluaran Pro agar tersedia. |
ValidateBuildContract::__construct(string $repoRoot) | Root repositori. | Menggunakan root repositori yang diberikan sebagai basis kontrak. | ValidateBuildContract | tidak ada yang diharapkan. | Validator kontrak tingkat skrip. |
ValidateBuildContract::run() | tidak ada. | Memeriksa input yang diperlukan dan asumsi build. | bool | Mengembalikan false pada kegagalan kontrak. | Jalankan sebelum keluaran build dipercaya. |
Konfigurasi Rector
Bagian berjudul “Konfigurasi Rector”Gunakan tabel ini untuk melihat berkas konfigurasi Rector yang menggerakkan tiap jalur target dan posisi tiap lintasan dalam pipeline lintasan-tunggal PHP 8.1 atau pipeline dua-lintasan PHP 7.4.
| Simbol | Parameter | Perilaku standar | Mengembalikan | Melempar atau gagal dengan | Catatan |
|---|---|---|---|---|---|
rector/config/rector-php81.php | Pohon sumber dan runtime Rector. | Penurunan versi lintasan tunggal ke target PHP 8.1. | Sumber yang ditransformasi. | Kegagalan parse atau transform Rector. | Digunakan untuk jalur distribusi PHP 8.1. |
rector/config/rector-php74-enums.php | Pohon sumber dan runtime Rector. | Lintasan PHP 7.4 pertama untuk konversi enum. | Sumber antara yang sudah ditransformasi. | Kegagalan parse atau transform Rector. | Berjalan sebelum lintasan PHP 7.4 penuh. |
rector/config/rector-php74.php | Sumber antara dan runtime Rector. | Lintasan penurunan versi PHP 7.4 penuh. | Sumber yang kompatibel dengan PHP 7.4. | Kegagalan parse atau transform Rector. | Digunakan untuk jalur distribusi PHP 7.4. |
Aturan kustom
Bagian berjudul “Aturan kustom”Gunakan tabel ini ketika Anda memelihara atau memperluas tiga aturan Rector khusus proyek dan memerlukan kontrak metode tiap aturan serta sintaks yang ditransformasinya.
| Simbol | Parameter | Perilaku standar | Mengembalikan | Melempar atau gagal dengan | Catatan |
|---|---|---|---|---|---|
DowngradeAsymmetricVisibilityRector | Properti atau parameter promosi yang menggunakan visibilitas asimetris. | Visibilitas biasa yang kompatibel dengan runtime lama. | Mempertahankan visibilitas baca jika memungkinkan. | Kegagalan aturan Rector. | Batasan setter hanya berlaku pada waktu kompilasi dan dihapus dalam keluaran yang dihasilkan. |
DowngradeAsymmetricVisibilityRector::getRuleDefinition() | tidak ada. | Mengembalikan metadata dan contoh aturan Rector. | RuleDefinition | tidak ada yang diharapkan. | Menjaga agar dokumentasi aturan tetap terlihat oleh perkakas Rector. |
DowngradeAsymmetricVisibilityRector::getNodeTypes() | tidak ada. | Memilih tipe node yang diperiksa oleh aturan. | array<class-string<Node>> | tidak ada yang diharapkan. | Cakupan sebaiknya tetap sempit demi transformasi yang deterministik. |
DowngradeAsymmetricVisibilityRector::refactor(Node $node) | Node AST. | Mengonversi visibilitas asimetris jika ada. | `Node | null` | Kegagalan aturan Rector. |
DowngradeCloneWithRector | clone() dengan penggantian properti. | Clone dengan penetapan properti eksplisit. | Menggunakan variabel sementara yang dihasilkan. | Kegagalan aturan Rector. | Harus berjalan setelah penurunan versi properti readonly. |
DowngradeCloneWithRector::getRuleDefinition() | tidak ada. | Mengembalikan metadata dan contoh aturan. | RuleDefinition | tidak ada yang diharapkan. | Digunakan oleh diagnostik Rector. |
DowngradeCloneWithRector::getNodeTypes() | tidak ada. | Memilih node return dan ekspresi. | array<class-string<Node>> | tidak ada yang diharapkan. | Menjaga agar aturan tetap berfokus pada sintaks clone-with. |
DowngradeCloneWithRector::refactor(Node $node) | Node AST. | Menulis ulang clone-with menjadi clone ditambah penetapan. | `array | null` | Kegagalan aturan Rector. |
DowngradeTraitConstantsRector | Konstanta trait dan referensi ke konstanta tersebut. | Properti statis dan referensi properti. | Mempertahankan visibilitas jika memungkinkan. | Kegagalan aturan Rector. | Menghapus final karena properti versi lama tidak boleh final. |
DowngradeTraitConstantsRector::getRuleDefinition() | tidak ada. | Mengembalikan metadata dan contoh aturan. | RuleDefinition | tidak ada yang diharapkan. | Digunakan oleh diagnostik Rector. |
DowngradeTraitConstantsRector::getNodeTypes() | tidak ada. | Memilih node trait dan class-constant-fetch. | array<class-string<Node>> | tidak ada yang diharapkan. | Menjaga agar aturan tetap terbatas pada konstanta trait. |
DowngradeTraitConstantsRector::refactor(Node $node) | Node AST. | Menulis ulang konstanta trait dan referensinya menjadi properti yang kompatibel. | `Node | null` | Kegagalan aturan Rector. |
Kontrak paket yang dihasilkan
Bagian berjudul “Kontrak paket yang dihasilkan”Gunakan tabel ini untuk melihat apa yang dipancarkan oleh builder: nama paket yang dipasang oleh proyek hilir dan paket yang membawa distribusi Pro.
| Paket yang dihasilkan | Peran runtime | Catatan |
|---|---|---|
nextpdf/backport | Distribusi runtime open-source yang dihasilkan. | Menggantikan paket nextpdf/* terpilih untuk runtime target. |
nextpdf/backport-pro | Distribusi Pro proprietary yang dihasilkan ketika sumber Pro tersedia. | Diterbitkan secara terpisah dari paket open-source. |
Catatan pengembangan
Bagian berjudul “Catatan pengembangan”- Builder mengonsumsi rilis sumber dan memancarkan artefak yang dihasilkan. Jangan menambal keluaran yang dihasilkan sebagai sumber kebenaran.
- Setiap aturan kustom harus memiliki uji fixture sebelum masuk ke dalam pipeline build.
- Job rilis harus memvalidasi keluaran yang dihasilkan pada runtime target, bukan hanya pada host build.