Pemecahan masalah NextPDF Backport Builder

Perkakas build — BUKAN dependensi runtime. Semua gejala pada halaman ini adalah kondisi saat build berjalan pada host pengelola atau continuous integration (CI). Tidak satu pun kondisi ini muncul pada aplikasi hilir.

Sekilas pandang

Build menjalankan lima tahap secara berurutan. Proses berhenti pada kegagalan pertama dan menampilkan nama tahap beserta pesannya. Baca nama tahap, lalu cari penyebab yang sesuai di bawah ini. Tahap-tahap tersebut adalah merge sources, run Rector downgrade, generate composer.json, copy static assets, dan validate output. Diverifikasi terhadap scripts/build.php (run() dan step()).

Tahap: merge sources

”Source repo '' not found at: ”

Tahap merge memvalidasi setiap repositori sumber yang diharapkan sebelum menyalin berkas. Jika ada repositori yang hilang, build dibatalkan dan menampilkan nama serta path-nya. Target PHP 8.1 mengharapkan nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, dan — jika Pro disertakan — nextpdf-Pro. Target PHP 7.4 hanya mengharapkan nextpdf. Diverifikasi terhadap scripts/merge-sources.php (loop validasi run(), peta repositori __construct()).

Solusi: lakukan checkout repositori sebagai direktori sejajar di bawah path yang diteruskan ke --source-dir, dan gunakan nama direktori persis seperti di atas. Dry run akan menampilkan daftar setiap repositori yang akan dibaca. Gunakan dry run untuk memastikan tata letaknya sebelum Anda menjalankan build penuh.

Tahap: run Rector downgrade

Rector keluar dengan kode non-nol

Orkestrator melaporkan Rector failed on <label> (exit code: N) lalu berhenti. Label tersebut mengidentifikasi pass yang gagal: public package, pro package, enum pre-processing, atau full downgrade. Diverifikasi terhadap scripts/build.php (runRectorPass()).

Crash resolver parameter-default pada nilai default enum (PHP 7.4)

Ini alasan target PHP 7.4 menggunakan dua pass. Resolver nilai-parameter-default Rector mengalami crash ketika enum case dipakai sebagai default constructor-promotion. Pass 1 (rector-php74-enums.php) mengonversi enum menjadi kelas constant-list terlebih dahulu. Dengan demikian, full pass pada Pass 2 tidak pernah melihat default enum case. Jika Anda melewati orkestrator dan menjalankan konfigurasi PHP 7.4 penuh langsung pada source yang berisi enum, crash ini akan terjadi. Diverifikasi terhadap scripts/build.php (komentar runRector() dan urutan dua-pass) dan rector/config/rector-php74-enums.php.

Skrip benchmark membuat Rector crash

rector-php81.php dan rector-php74.php melewati */tests/Benchmark/*. Skrip-skrip tersebut merujuk pustaka Portable Document Format (PDF) eksternal yang tidak dapat di-resolve oleh Rector, sehingga membuat resolver parameter-default crash. Jika path benchmark ikut diproses, berarti glob skip tersebut hilang atau path-nya berbeda. Diverifikasi terhadap pemanggilan withSkip().

MHASH_XXH* crash (PHP 7.4)

rector-php74.php melewati DowngradeHashAlgorithmXxHashRector. Aturan bawaan tersebut mengalami crash pada konstanta xxHash. Source tidak memakai xxHash, sehingga skip ini aman. Diverifikasi terhadap rector/config/rector-php74.php (withSkip()).

Tahap: post-Rector fix-ups (hanya PHP 7.4)

Fix-up dijalankan di antara kedua pass. Fix-up menulis ulang pola yang ditinggalkan oleh aturan enum-to-class. Jika output PHP 7.4 memiliki parse error yang melibatkan EnumClass::Case->value, ->name, mantan metode enum yang dipanggil sebagai metode instance, atau argumen bernama pada tipe yang tidak ter-resolve, berarti fix-up tidak mengenali pola tersebut. Keterbatasan clone-with juga berlaku di sini: pencocokan argumen bersifat non-rekursif, sehingga nilai override dengan tanda kurung bersarang tidak ditulis ulang. Diverifikasi terhadap scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) dan rector/rules/DowngradeCloneWithRector.php (keterbatasan yang terdokumentasi).

Tahap: generate composer.json

Tahap ini memindahkan direktori src/ dan tests/ yang sudah diproses dari direktori build-temp ke direktori output. Setelah itu, tahap ini menulis composer.json yang dihasilkan. Kegagalan di sini hampir selalu merupakan kondisi sistem berkas: direktori output tidak dapat ditulis, atau pohon build-temp hilang karena Rector tidak menghasilkan apa pun. Diverifikasi terhadap scripts/build.php (adjustComposer(), moveTree()).

Tahap: copy static assets

Tahap ini menyalin LICENSE dari repositori sumber inti dan menulis CHANGELOG.md yang dihasilkan. Jika LICENSE tidak ada, penyalinan dilewati tanpa pesan dan build tetap berlanjut; changelog selalu ditulis. Kegagalan di sini berarti direktori output menjadi tidak dapat ditulis di tengah proses build. Diverifikasi terhadap scripts/build.php (copyStaticAssets()).

Tahap: validate output

”Output src/ directory not found” / “No PHP files found in output” (direktori keluaran tidak ditemukan)

Validasi memerlukan output/src yang tidak kosong. Pohon kosong berarti tahap merge tidak menyalin apa pun, atau pemindahan berkas gagal. Diverifikasi terhadap scripts/build.php (validateOutput()).

”Syntax validation: skipped (requires PHP runtime)”

Kondisi ini memang diharapkan, bukan error. Host build menjalankan PHP modern, bukan runtime target, sehingga tahap lokal hanya menghitung berkas dan menampilkan perintah Docker untuk pemeriksaan sintaks yang sesungguhnya. Gerbang sintaks otoritatif adalah langkah php -l pasca-build dalam alur kerja rilis, yang berjalan di runtime target yang sesungguhnya. Diverifikasi terhadap scripts/build.php (validateOutput()) dan .github/workflows/build.yml (langkah pemeriksaan-sintaks PHP 8.1 / PHP 7.4).

Keterbatasan yang diketahui

Keterbatasan ini melekat pada pendekatan downgrade. Keterbatasan tersebut diverifikasi terhadap aturan-aturan dan bagian “Known Limitations” pada README.md proyek:

• Properti readonly dihapus. Build menghapus readonly agar ekspansi clone-with dapat menetapkan properti secara eksplisit pada runtime lama. Output yang telah di-downgrade tidak lagi memiliki imutabilitas yang ditegakkan oleh runtime.
• #[Override] tidak ditegakkan pada PHP 8.1. Atribut tersebut mungkin tetap ada, tetapi runtime lama tidak menegakkannya.
• Target PHP 7.4 hanya untuk core. Adapter framework, lapisan kompatibilitas tcpdf, dan Pro dikecualikan dari distribusi PHP 7.4 sesuai konstruksi skrip build.
• Pro adalah paket terpisah dan hanya untuk PHP 8.1. Tidak ada build Pro untuk PHP 7.4.
• Pencocokan argumen clone-with bersifat non-rekursif. Nilai override yang mengandung tanda kurung bersarang tidak ditransformasi, dan hanya kunci array bertipe string yang ter-resolve menjadi nama properti.

Berikutnya

• /integrations/backport/configuration/ — referensi aturan dan flag.
• /integrations/backport/production-usage/ — gerbang CI dan jalur rilis.