Panduan cepat untuk NextPDF Backport Builder

Perkakas build — bukan dependensi runtime. Jalankan panduan ini di host maintainer atau continuous integration (CI). Arsip yang Anda hasilkan dikonsumsi oleh proyek downstream. Langkah-langkah ini tidak pernah dijalankan di server aplikasi.

Sekilas pandang

Anda akan menjalankan tiga perintah. Pertama, lakukan dry-run untuk memastikan pipeline sudah terhubung tanpa menyentuh berkas apa pun. Berikutnya, jalankan build PHP 8.1 penuh. Setelah itu, jalankan build PHP 7.4 penuh. Setiap langkah memakai satu perintah, baik melalui skrip Composer maupun pemanggilan scripts/build.php yang terdokumentasi.

Prasyarat

• Host build dengan PHP >=8.4 <9.0 dan dependensi build terpasang (composer install, tanpa --no-dev). Lihat /integrations/backport/install/.
• Repositori sumber di-checkout sebagai direktori sejajar di bawah satu source root. Build PHP 8.1 membaca nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, dan nextpdf-Pro (untuk Pro). Build PHP 7.4 hanya membaca nextpdf. Diverifikasi terhadap scripts/merge-sources.php.

Langkah 1 — dry-run

Dry-run menjalankan setiap tahap dalam mode laporan saja. Tahap penggabungan mencantumkan berkas yang akan disalin. Perintah ini menyebutkan Rector, tetapi tidak menjalankannya. Tahap pembuatan composer, penyalinan aset, dan validasi mencetak rencana masing-masing. Tidak ada yang ditulis. Jalankan ini terlebih dahulu karena inilah cara tercepat untuk memastikan tata letak sumber dan flag Anda.

composer build:dry

composer build:dry dipetakan ke php scripts/build.php --dry-run. Diverifikasi terhadap composer.jsonscripts dan scripts/build.php (cabang dryRun di setiap tahap). Dengan flag standar, targetnya adalah php81, dan source root memakai nilai standar skrip. Anda dapat menimpa salah satu nilai tersebut, seperti yang ditunjukkan pada langkah 2.

Jika dry-run melaporkan repositori sumber yang hilang, proses langsung berhenti dan menyebutkan nama repositori tersebut. Perbaiki tata letak sumber sebelum Anda melanjutkan. Lihat /integrations/backport/troubleshooting/.

Langkah 2 — build PHP 8.1 penuh

Build PHP 8.1 menjalankan beberapa langkah secara berurutan: menggabungkan core dengan adapter framework dan lapisan kompatibilitas tcpdf, menjalankan konfigurasi Rector single-pass, menghasilkan nextpdf/backportcomposer.json, menyalin lisensi, menulis CHANGELOG.md, lalu menghitung berkas PHP yang dihasilkan.

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

Diverifikasi terhadap titik masuk command-line interface (CLI) scripts/build.php. Lima tahap berjalan berurutan: menggabungkan sumber, menjalankan downgrade Rector, menghasilkan composer.json, menyalin aset statis, dan memvalidasi keluaran. Setiap tahap mencetak tanda centang ketika berhasil. Tahap pertama yang gagal akan menghentikan build dan mencetak galatnya. Untuk mengecualikan Pro, tambahkan --no-pro.

Saat build berhasil, orkestrator mencetak waktu yang berlalu dan path keluaran. Jika Pro disertakan, orkestrator juga mencetak path keluaran Pro. Direktori keluaran kemudian berisi src/, tests/, composer.json yang dihasilkan, yang mendeklarasikan peta replace dan kebutuhan polyfill, serta LICENSE dan CHANGELOG.md.

Langkah 3 — build PHP 7.4 penuh

Build PHP 7.4 hanya mencakup core dan memakai pipeline two-pass. Build ini menjalankan pra-pemrosesan enum, membersihkan cache, menerapkan perbaikan pasca-Rector, lalu melakukan downgrade penuh.

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

Diverifikasi terhadap scripts/build.php. Di sini, --target=php74 memaksa mode core-only, menonaktifkan Pro, dan membuat runRector() memilih jalur two-pass. composer.json yang dihasilkan menggunakan constraint >=7.4 <8.1. Build ini hanya menggantikan nextpdf/core dan menambahkan polyfill PHP 8.0 dan 8.1 selain polyfill 8.2–8.5.

Langkah 4 — baca keluaran

Tahap validasi menghitung berkas PHP di output/src dan gagal jika jumlahnya nol. Tahap ini tidak menjalankan pemeriksaan sintaks secara lokal. Interpreter lokal adalah PHP modern pada host build, bukan runtime target. Sebagai gantinya, tahap ini mencetak perintah Docker untuk memvalidasi terhadap runtime target yang sebenarnya. Diverifikasi terhadap scripts/build.php (validateOutput()).

Untuk validasi penuh, jalankan pemeriksaan sintaks dengan PHP target. Alur kerja rilis mengikuti jalur yang sama. Alur kerja ini memeriksa sintaks keluaran pada PHP 8.1 (atau PHP 7.4), lalu memasang dan mengujinya di seluruh matriks dukungan. Lihat /integrations/backport/production-usage/.

Apa yang telah Anda bangun

Artefak	Dibangun oleh	Constraint	Menggantikan
nextpdf/backport (PHP 8.1)	Langkah 2	>=8.1 <8.5	core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro (PHP 8.1)	Langkah 2, ketika Pro disertakan	>=8.1 <8.5	nextpdf/pro
nextpdf/backport (PHP 7.4)	Langkah 3	>=7.4 <8.1	nextpdf/core

Diverifikasi terhadap scripts/adjust-composer.php.

Berikutnya

• /integrations/backport/production-usage/ — Sambungkan ini ke alur kerja rilis berbasis peristiwa.
• /integrations/backport/configuration/ — Referensi aturan dan flag di balik perintah-perintah ini.
• /integrations/backport/troubleshooting/ — Setiap kegagalan tahap dan maknanya.