Menginstal NextPDF Backport Builder

Instal perkakas build ini di workstation maintainer atau runner continuous integration (CI). Perkakas ini BUKAN dependensi runtime. Aplikasi downstream tidak pernah menginstal builder; aplikasi tersebut menginstal paket yang dihasilkan oleh builder.

Sekilas pandang

Ada dua jenis audiens dengan kebutuhan instalasi yang berbeda:

Maintainer atau operator CI meng-clone repositori ini dan menginstal dependensi build-nya. Instal nextpdf/backport-builder hanya dalam konteks ini.
Aplikasi downstream yang berjalan pada runtime PHP yang lebih lama menginstal paket nextpdf/backport yang dihasilkan dari kanal rilisnya. Aplikasi tersebut tidak pernah menyentuh repositori ini.

Halaman ini mencakup kedua alur kerja tersebut. Baca bagian yang sesuai dengan peran Anda.

Instalasi host build

Persyaratan

Dependensi	Batasan	Sumber kebenaran
PHP	`>=8.4 <9.0`	`composer.jsonrequire.php`
Composer	2.6+	Tabel environment di `CONTRIBUTING.md`
`rector/rector`	`^2.0`	`composer.jsonrequire-dev`
`phpstan/phpstan`	`^2.1`	`composer.jsonrequire-dev`
`phpunit/phpunit`	`^13.0`	`composer.jsonrequire-dev`

Alur kerja CI menyediakan PHP 8.5 untuk job build dan job dry-run. Setiap host build yang menjalankan versi PHP dalam rentang >=8.4 <9.0 memenuhi batasan Composer. Parser PHP harus dapat menerima sintaks terbaru yang digunakan oleh kode sumber. Diverifikasi terhadap .github/workflows/0-ci.yml.

Langkah-langkah

Clone repositori, lalu checkout branch untuk target yang ingin Anda build. PHP74 adalah branch default dan menghasilkan distribusi PHP 7.4 yang hanya berisi core. PHP81 menghasilkan distribusi PHP 8.1 dengan semua adapter.
Terminal window
```
git clone https://github.com/nextpdf-labs/backport.git
cd backport
git checkout PHP74
```
Instal dependensi build. Jangan menyertakan --no-dev: engine Rector, PHPStan, dan PHPUnit berada di require-dev, dan build tidak dapat berjalan tanpanya.
Terminal window
```
composer install --prefer-dist --no-progress
```
Pastikan toolchain berhasil di-resolve. Skrip analyse menjalankan PHPStan pada level 10 terhadap rector/rules dan scripts. Hasil eksekusi yang bersih menunjukkan bahwa kode build itu sendiri sudah benar sebelum Anda menghasilkan keluaran.
Terminal window
```
composer analyse
```
Jalankan pengujian fixture untuk aturan. Setiap aturan Rector kustom memiliki suite fixture yang memastikan transformasi before/after yang tepat.
Terminal window
```
composer test
```

Setelah langkah 4, host siap melakukan build. Buka /integrations/backport/quickstart/ untuk invokasi dry-run dan build penuh.

Ekspektasi pohon sumber

Build menggabungkan beberapa repositori sumber menjadi satu pohon. Tempatkan repositori-repositori tersebut sebagai direktori yang sejajar di bawah satu root sumber; skrip merge mengacu pada setiap direktori berdasarkan namanya. Untuk target PHP 8.1, build membaca nextpdf (core), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, dan nextpdf-Pro ketika Pro disertakan. Untuk target PHP 7.4, build hanya membaca nextpdf. Diverifikasi terhadap scripts/merge-sources.php (MergeSources::__construct()). Tentukan root sumber dengan --source-dir. Lihat /integrations/backport/configuration/ untuk referensi flag.

Penggunaan paket yang dihasilkan di sisi downstream

Saat Anda mendukung proyek yang berjalan pada runtime PHP yang lebih lama, instal distribusi yang dihasilkan, bukan builder ini.

PHP 8.1 hingga 8.3

composer require nextpdf/backport

Paket yang diinstal mendeklarasikan batasan >=8.1 <8.5 dan menggantikan nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter, dan nextpdf/compat-legacy. Kode aplikasi tetap mengimpor namespace NextPDF\ tanpa perubahan. Paket melakukan autoload terhadap pohon yang telah digabung melalui satu prefix PHP Standard Recommendation 4 (PSR-4), yaitu NextPDF\ yang dipetakan ke src/. Sebuah autoloader PSR-4 menambahkan nama kelas relatif ke direktori dasar yang terdaftar untuk prefix tersebut (PHP-FIG PSR-4). Diverifikasi terhadap scripts/adjust-composer.php (buildPublicAutoloadMap(), buildReplace()).

PHP 7.4 hingga 8.0

composer require nextpdf/backport

Distribusi PHP 7.4 hanya berisi core. Distribusi ini mendeklarasikan batasan >=7.4 <8.1 dan hanya menggantikan nextpdf/core. Adapter framework, lapisan kompatibilitas tcpdf, dan Pro tidak disertakan dalam distribusi PHP 7.4. Diverifikasi terhadap scripts/adjust-composer.php dan scripts/build.php (target PHP 7.4 memaksa hanya core). Proyek yang memerlukan adapter framework membutuhkan PHP 8.1 atau yang lebih baru.

Pro

composer require nextpdf/backport-pro

Distribusi Pro adalah paket terpisah, nextpdf/backport-pro, dengan lisensi proprietary. Distribusi ini membutuhkan nextpdf/backport pada major.minor yang sesuai dan menambahkan phpseclib/phpseclib ^3.0. Distribusi ini hanya dihasilkan untuk target PHP 8.1. Diverifikasi terhadap scripts/adjust-composer.php (generateProComposer()).

Distribusi PHP 7.4 dan distribusi Pro saling eksklusif: berdasarkan rancangan skrip build, tidak ada build Pro untuk PHP 7.4.

Polyfill dalam paket yang dihasilkan

composer.json yang dihasilkan membutuhkan paket symfony/polyfill-* agar fungsi standard-library yang lebih baru dapat di-resolve di runtime target. Target PHP 8.1 membutuhkan polyfill untuk PHP 8.2 hingga 8.5. Target PHP 7.4 juga membutuhkan polyfill PHP 8.0 dan 8.1. Polyfill ini adalah dependensi runtime dari paket yang dihasilkan, bukan dari builder. Diverifikasi terhadap scripts/adjust-composer.php (generatePublicComposer()).

Berikutnya

/integrations/backport/configuration/ — Konfigurasi Rector, aturan kustom, dan referensi flag build.
/integrations/backport/quickstart/ — dry-run dan build penuh pertama Anda.