Gambaran umum NextPDF Backport Builder
Perkakas build, bukan dependensi runtime. Pengelola NextPDF menggunakan paket ini untuk menghasilkan distribusi NextPDF yang kompatibel dengan PHP 8.1+ dan PHP 7.4+. Aplikasi tidak boleh menambahkannya sebagai dependensi runtime.
Sekilas pandang
Bagian berjudul “Sekilas pandang”NextPDF Backport Builder adalah infrastruktur build untuk menghasilkan distribusi ekosistem NextPDF versi turun (downgrade) bagi runtime PHP yang lebih lama daripada baseline pengembangan. NextPDF ditulis untuk versi PHP modern dan menggunakan sintaks yang ditolak oleh interpreter versi sebelumnya. Builder ini meneruskan kode sumber melalui Rector, mesin yang mentransformasi abstract syntax tree, lalu menghasilkan paket dengan sintaks yang dapat diterima oleh runtime PHP 8.1 atau PHP 7.4.
Nama paket Composer-nya adalah nextpdf/backport-builder. Paket ini mendeklarasikan "type": "project" dan tidak membawa dependensi runtime NextPDF apa pun. Kebutuhannya terbatas pada mesin build (rector/rector), analisis statis (phpstan/phpstan), test runner (phpunit/phpunit), serta sekumpulan paket symfony/polyfill-* yang digunakan dalam keluaran yang dihasilkan. composer.json di root repositori memverifikasi hal ini.
Apa yang bukan paket ini
Bagian berjudul “Apa yang bukan paket ini”Repositori ini tidak berisi mesin NextPDF. Repositori ini berisi aturan dan skrip yang mengubah mesin tersebut menjadi bentuk backport. Pemisahan ini memiliki tiga dampak praktis:
- Anda tidak memasang paket ini untuk merender PDF. Pasang
nextpdf/backport, artefak yang dihasilkan oleh builder ini. Simpan builder di host pengelola atau host continuous integration (CI). - Anda tidak mengembangkan kode berdasarkan kode yang dihasilkan. Distribusi yang dihasilkan adalah artefak read-only yang diproduksi oleh mesin. Kirimkan laporan bug dan permintaan fitur ke repositori sumber
nextpdf/*asli. - Keluaran dikirim sebagai tag versi, bukan sebagai branch dari repositori ini. Pipeline rilis memberi tag pada tree yang dihasilkan dan melampirkan arsip ke rilis GitHub.
Apa yang dihasilkannya
Bagian berjudul “Apa yang dihasilkannya”Builder menghasilkan paket Composer dengan nama dan lisensi yang ditetapkan oleh scripts/adjust-composer.php:
| Paket yang dihasilkan | Lisensi | Cakupan | Dibangun saat |
|---|---|---|---|
nextpdf/backport | Apache-2.0 | Core, adapter framework, dan lapisan kompatibilitas tcpdf untuk target PHP 8.1 | Selalu |
nextpdf/backport-pro | proprietary | Modul Pro, dihasilkan sebagai paket terpisah | Target PHP 8.1, ketika sumber Pro tersedia dan Pro tidak dikecualikan |
Paket nextpdf/backport mendeklarasikan entri replace Composer sehingga, setelah dipasang, paket ini memenuhi batasan paket aslinya. Untuk target PHP 8.1, paket yang digantikan adalah nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter, dan nextpdf/compat-legacy. Untuk target PHP 7.4, hanya nextpdf/core yang digantikan karena build PHP 7.4 hanya mencakup core. scripts/adjust-composer.php (buildReplace()) memverifikasi hal ini.
Autoloader milik konsumen menyelesaikan tree gabungan melalui satu prefiks PHP Standards Recommendation 4 (PSR-4), NextPDF\, yang dipetakan ke src/. PSR-4 memetakan prefiks namespace ke direktori dasar dan menyelesaikan setiap nama kelas yang berkualifikasi penuh menjadi sebuah berkas di bawah direktori tersebut; lihat PHP framework Interop Group (PHP-FIG) PSR-4. Paket Pro memetakan NextPDF\Pro\ ke src/ miliknya sendiri.
Matriks PHP yang didukung
Bagian berjudul “Matriks PHP yang didukung”Matriks di bawah ini hanya mencakup hal-hal yang ditegakkan oleh konfigurasi Rector dan skrip build. Host build selalu menjalankan versi PHP modern. Keluaran-nya menyasar versi yang lebih lama.
| Aspek | Nilai | Bukti |
|---|---|---|
| PHP host build | >=8.4 <9.0 | composer.jsonrequire.php |
| PHP build/test CI | 8.5 | .github/workflows/0-ci.yml, build.yml (shivammathur/setup-phpphp-version: '8.5') |
| Batasan keluaran target PHP 8.1 | >=8.1 <8.5 | scripts/adjust-composer.php (generatePublicComposer()) |
| Batasan keluaran target PHP 7.4 | >=7.4 <8.1 | scripts/adjust-composer.php (generatePublicComposer()) |
| Cakupan target PHP 8.1 | Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, terpisah) | scripts/merge-sources.php, scripts/adjust-composer.php |
| Cakupan target PHP 7.4 | Hanya core | scripts/build.php (--target=php74 memaksa hanya-core, Pro dinonaktifkan) |
Build PHP 8.1 divalidasi pada PHP 8.1, 8.2, 8.3, dan 8.4. Build PHP 7.4 divalidasi pada PHP 7.4 dan 8.0. Matriks job validate-php81 dan validate-php74 di .github/workflows/build.yml memverifikasi hal ini. Itulah runtime yang dijalankan oleh pipeline. Ini adalah set validasi yang teramati, bukan klaim kesesuaian.
Model dua branch
Bagian berjudul “Model dua branch”Repositori ini tidak memiliki branch main. PHP74 adalah branch default, dan PHP81 adalah branch permanen kedua. Branch yang Anda gunakan menentukan dua hal: target default build lokal dan set sumber yang digabungkan. Terapkan perubahan yang memengaruhi kedua target ke masing-masing branch melalui pull request tersendiri. Alur kerja CI berjalan pada kedua branch, PHP74 dan PHP81. Hal ini diverifikasi terhadap git branch -a dan .github/workflows/0-ci.yml (branches: [PHP74, PHP81]).
Bagaimana sebuah rilis terjadi
Bagian berjudul “Bagaimana sebuah rilis terjadi”Alur rilis digerakkan oleh peristiwa. Ketika organisasi sumber NextPDF menerbitkan tag rilis, peristiwa repository-dispatch bertipe source-release memicu alur kerja build. Alur kerja ini melakukan checkout setiap repositori sumber pada tag yang cocok, menjalankan pipeline, memeriksa sintaks keluaran pada runtime target, memvalidasinya di seluruh matriks dukungan, dan melampirkan arsip ke rilis GitHub. Tag versinya mengikuti Semantic Versioning: nomor versi adalah MAJOR.MINOR.PATCH atas API publik yang dideklarasikan (Semantic Versioning 2.0.0 §2). .github/workflows/build.yml memverifikasi hal ini.
Ke mana selanjutnya
Bagian berjudul “Ke mana selanjutnya”- /integrations/backport/install/ — cara memasang builder pada host build, dan cara konsumen memasang paket yang dihasilkan.
- /integrations/backport/configuration/ — konfigurasi Rector, aturan kustom, dan flag build.
- /integrations/backport/quickstart/ — dry run berbasis sumber dan pemanggilan build penuh.
- /integrations/backport/production-usage/ — cara menghubungkan builder ke dalam alur kerja rilis.
- /integrations/backport/troubleshooting/ — mode kegagalan yang dicegah oleh pipeline dan cara membacanya.
- /integrations/backport/security-and-operations/ — postur rantai pasok, batas kepercayaan, dan jaminan operasional.
- /integrations/backport/boot-and-discovery/ — cara builder menemukan modul sumber dan melakukan boot.
- /integrations/backport/integration/ — kontrak integrasi host build.