Mengonfigurasi NextPDF Backport Builder

Perkakas build — BUKAN dependensi runtime. Semua yang dibahas di halaman ini mengonfigurasi transformasi sumber saat build. Tidak ada satu pun yang dikirimkan ke runtime hilir.

Sekilas

Tiga berkas konfigurasi Rector di bawah rector/config/ dan tiga aturan khusus di bawah rector/rules/ menjalankan transformasi ini. Konfigurasi yang digunakan bergantung pada target. Target PHP 8.1 memakai satu lintasan Rector. Target PHP 7.4 memakai alur dua-lintasan dengan tahap perbaikan di antara keduanya. Lintasan kedua diperlukan karena Rector tidak dapat menyelesaikan nilai bawaan case enum dalam satu lintasan.

Konfigurasi Rector

Berkas	Tujuan	Dipakai oleh
rector/config/rector-php81.php	Downgrade satu lintasan ke PHP 8.1	Target PHP 8.1
rector/config/rector-php74-enums.php	Lintasan 1 — mengonversi enum menjadi kelas daftar-konstanta	Target PHP 7.4
rector/config/rector-php74.php	Lintasan 2 — downgrade penuh ke PHP 7.4	Target PHP 7.4

Setiap konfigurasi memanggil rantai downgrade-set milik Rector (withDowngradeSets(php81: true) atau withDowngradeSets(php74: true)) untuk fitur yang ditangani secara native oleh Rector. Selanjutnya, konfigurasi tersebut mendaftarkan aturan khusus untuk fitur yang tersisa. Hal ini diverifikasi terhadap ketiga berkas di rector/config/.

Aturan yang dilewati

rector-php81.php dan rector-php74.php sama-sama mengecualikan */tests/Benchmark/*. Skrip benchmark merujuk ke pustaka Portable Document Format (PDF) eksternal yang tidak dapat diselesaikan oleh Rector, sehingga penyelesai parameter bawaannya gagal. rector-php74.php juga mengecualikan DowngradeHashAlgorithmXxHashRector. Aturan bawaan tersebut gagal pada konstanta MHASH_XXH* yang sudah usang di PHP modern, dan sumbernya tidak menggunakan xxHash. Hal ini diverifikasi terhadap pemanggilan withSkip() di kedua berkas.

Tiga aturan khusus

Repositori ini hanya menyertakan tiga aturan Rector khusus. Ketiganya didaftarkan di rector-php81.php; aturan asymmetric-visibility, clone-with, dan trait-constants juga didaftarkan di rector-php74.php. tests/Rector/RectorRulesMetadataTest.php menegaskan hal ini secara langsung dengan membuat instance setiap aturan serta memeriksa definisi dan tipe node-nya.

DowngradeAsymmetricVisibilityRector

Menghapus modifier set asymmetric-visibility. Properti atau parameter terpromosi yang dideklarasikan public private(set) menjadi public biasa. Akses baca dipertahankan; pembatasan setter pada waktu kompilasi dihilangkan. Jika tidak ada visibilitas baca yang tersisa, aturan ini menggunakan public sebagai standar. Transformasi ini berdasarkan sumber dari tests/Rector/Fixtures/DowngradeAsymmetricVisibility/public_private_set.php.inc:

before

<?php

class Config {
    public private(set) float $x = 0.0;
    public private(set) string $name = '';
    public private(set) int $count = 0;
}

after

<?php

class Config {
    public float $x = 0.0;
    public string $name = '';
    public int $count = 0;
}

DowngradeCloneWithRector

Menulis ulang bentuk fungsi clone() dengan larik override menjadi operasi clone, penetapan properti eksplisit, dan pengembalian variabel sementara. Penghitung variabel sementara diatur ulang per berkas. Aturan ini harus dijalankan setelah aturan penghapusan properti readonly, karena jika tidak, penetapan yang diperluas akan gagal pada properti readonly. Transformasi ini berdasarkan sumber dari tests/Rector/Fixtures/DowngradeCloneWith/return_clone_with.php.inc:

before

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self {
        return clone($this, ['width' => $width, 'height' => $height]);
    }
}

after

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self
    {
        $__cloneResult1 = clone $this;
        $__cloneResult1->width = $width;
        $__cloneResult1->height = $height;
        return $__cloneResult1;
    }
}

Aturan ini memiliki keterbatasan yang terdokumentasi. Pencocokan argumen menggunakan pola non-rekursif, sehingga nilai override dengan tanda kurung bersarang tidak ditangani. Hanya kunci larik bertipe string yang diselesaikan menjadi nama properti. Hal ini diverifikasi terhadap rector/rules/DowngradeCloneWithRector.php beserta rangkaian fixture-nya.

DowngradeTraitConstantsRector

Mengonversi konstanta trait menjadi properti statis. Runtime yang lebih lama menolak konstanta trait dengan “Traits cannot have constants”. Aturan ini juga menulis ulang referensi self::CONST dan static::CONST menjadi bentuk properti statis. Visibilitas dipertahankan; modifier final dihapus karena properti tidak boleh final pada target yang lebih lama. Konstanta kelas bertipe diubah menjadi properti bertipe. Transformasi ini berdasarkan sumber dari tests/Rector/Fixtures/DowngradeTraitConstants/private_constant.php.inc:

before

<?php

trait HasLimit
{
    private const MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::MAX_SIZE;
    }
}

after

<?php

trait HasLimit
{
    private static $MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::$MAX_SIZE;
    }
}

Alur dua-lintasan PHP 7.4

Target PHP 7.4 tidak dapat diproses dalam satu lintasan. Penyelesai nilai parameter bawaan Rector gagal pada nilai bawaan case enum dalam promosi konstruktor. Karena itu, skrip build menjalankan:

1. Lintasan 1 — prapemrosesan enum. rector-php74-enums.php hanya menjalankan aturan bawaan enum-to-constant-list-class. Setelah lintasan ini, case enum menjadi konstanta kelas biasa.
2. Pembersihan cache. Cache Rector dibersihkan agar lintasan kedua tidak membaca pohon lama.
3. Perbaikan pascapemrosesan. scripts/build.php menulis ulang pola yang tidak dicakup aturan enum-to-class. Metode instance enum yang sebelumnya ada dibuat menjadi statis. Akses EnumClass::Case->value dan ->name diselesaikan. Argumen bernama yang tidak dapat diikat Rector diratakan menjadi argumen posisional. Tanpa perbaikan ini, pola sintaks tersebut akan menyebabkan kesalahan parse pada PHP 7.4.
4. Lintasan 2 — downgrade penuh. rector-php74.php menjalankan rantai downgrade PHP 7.4 lengkap, ditambah aturan khusus.

Diverifikasi terhadap scripts/build.php (runRector(), postProcessFixups()).

Referensi tanda build

scripts/build.php mengatur proses build. Opsinya diverifikasi terhadap pemanggilan getopt() dan konstruktor Build:

Tanda	Standar	Efek
--version=<x.y.z>	2.0.0	Versi yang ditulis ke dalam composer.json dan CHANGELOG.md yang dihasilkan
--source-dir=<path>	c:/Users/admin/Documents	Akar yang memuat repositori sumber sibling
--output-dir=<path>	<repo>/output	Lokasi penulisan distribusi yang dihasilkan
--target=php74 | --target=php81	php81	Target downgrade. php74 memaksa mode core saja dan menonaktifkan Pro
--dry-run	mati	Menjalankan setiap tahap dalam mode laporan saja; penyalinan dan Rector dilewati
--no-pro	mati	Mengecualikan paket Pro (hanya target PHP 8.1; PHP 7.4 sudah mengecualikannya)

Nilai --target yang tidak valid melempar InvalidArgumentException sebelum pekerjaan apa pun dimulai. Hal ini diverifikasi terhadap Build::__construct() (validasi VALID_TARGETS).

Skrip Composer

Skrip	Perintah	Tujuan
composer test	phpunit	Menjalankan jaringan fixture aturan
composer analyse	phpstan analyse rector/rules scripts --level=10	Menganalisis kode build secara statis
composer build	php scripts/build.php	Build penuh
composer build:dry	php scripts/build.php --dry-run	Build uji jalan (dry-run)

Diverifikasi terhadap composer.jsonscripts.

Berikutnya

• /integrations/backport/quickstart/ — jalankan uji jalan dan build penuh.
• /integrations/backport/troubleshooting/ — arti setiap tahap kegagalan.