Bỏ qua để đến nội dung
NextPDF

Cấu hình NextPDF Backport Builder

Công cụ build — KHÔNG phải là phụ thuộc lúc chạy. Mọi nội dung trên trang này dùng để cấu hình việc biến đổi mã nguồn tại thời điểm build. Không phần nào trong đó được đưa vào runtime ở phía sau.

Tổng quan nhanh

Phần tiêu đề “Tổng quan nhanh”

Ba tệp cấu hình Rector trong rector/config/ và ba quy tắc tùy chỉnh trong rector/rules/ điều khiển quá trình biến đổi. Cấu hình được chọn tùy theo mục tiêu. Mục tiêu PHP 8.1 dùng một lượt Rector. Mục tiêu PHP 7.4 dùng quy trình hai lượt, kèm một giai đoạn sửa chữa ở giữa. Lượt thứ hai là bắt buộc vì Rector không thể phân giải các giá trị mặc định của enum case chỉ trong một lần duyệt.

Cấu hình Rector

Phần tiêu đề “Cấu hình Rector”
TệpMục đíchĐược dùng bởi
rector/config/rector-php81.phpHạ cấp một lượt xuống PHP 8.1Mục tiêu PHP 8.1
rector/config/rector-php74-enums.phpLượt 1 — chuyển enum thành các lớp danh sách hằng sốMục tiêu PHP 7.4
rector/config/rector-php74.phpLượt 2 — hạ cấp toàn bộ xuống PHP 7.4Mục tiêu PHP 7.4

Mỗi cấu hình gọi chuỗi downgrade-set của Rector (withDowngradeSets(php81: true) hoặc withDowngradeSets(php74: true)) cho các tính năng mà Rector có thể xử lý trực tiếp. Sau đó, cấu hình đăng ký các quy tắc tùy chỉnh cho những tính năng còn lại. Đã đối chiếu với ba tệp trong rector/config/.

Quy tắc bỏ qua

Phần tiêu đề “Quy tắc bỏ qua”

rector-php81.php và rector-php74.php đều bỏ qua */tests/Benchmark/*. Các script benchmark tham chiếu đến những thư viện Portable Document Format (PDF) bên ngoài mà Rector không thể phân giải, khiến bộ phân giải tham số mặc định của nó bị lỗi. rector-php74.php cũng bỏ qua DowngradeHashAlgorithmXxHashRector. Quy tắc tích hợp đó bị lỗi với các hằng số MHASH_XXH* vốn không còn được dùng trong PHP hiện đại, trong khi mã nguồn không sử dụng xxHash. Đã đối chiếu với các lệnh gọi withSkip() trong cả hai tệp.

Ba quy tắc tùy chỉnh

Phần tiêu đề “Ba quy tắc tùy chỉnh”

Kho lưu trữ cung cấp đúng ba quy tắc Rector tùy chỉnh. Cả ba đều được đăng ký trong rector-php81.php; các quy tắc asymmetric-visibility, clone-with và trait-constants cũng được đăng ký trong rector-php74.php. tests/Rector/RectorRulesMetadataTest.php xác nhận trực tiếp điều này bằng cách khởi tạo từng quy tắc rồi kiểm tra phần định nghĩa cùng các kiểu node của quy tắc đó.

DowngradeAsymmetricVisibilityRector

Phần tiêu đề “DowngradeAsymmetricVisibilityRector”

Loại bỏ bộ điều chỉnh set của asymmetric-visibility. Một thuộc tính hoặc tham số được nâng cấp và khai báo là public private(set) sẽ trở thành public thông thường. Quyền truy cập đọc được giữ nguyên; ràng buộc setter lúc biên dịch bị loại bỏ. Khi không còn quyền hiển thị đọc nào, quy tắc mặc định về public. Biến đổi này dựa trên mã nguồn từ 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

Phần tiêu đề “DowngradeCloneWithRector”

Viết lại dạng hàm clone() kèm mảng ghi đè thành một lệnh clone, các phép gán thuộc tính tường minh và một câu lệnh return biến tạm. Bộ đếm biến tạm được đặt lại theo từng tệp. Quy tắc này phải chạy sau quy tắc loại bỏ thuộc tính readonly, vì nếu không, phép gán được mở rộng sẽ thất bại với thuộc tính readonly. Biến đổi này dựa trên mã nguồn từ 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;
    }
}

Quy tắc có những hạn chế đã được ghi nhận. Việc khớp đối số dùng một mẫu không đệ quy, nên các giá trị ghi đè có dấu ngoặc lồng nhau sẽ không được xử lý. Chỉ các khóa mảng kiểu chuỗi mới được phân giải thành tên thuộc tính. Đã đối chiếu với rector/rules/DowngradeCloneWithRector.php và bộ fixture của quy tắc này.

DowngradeTraitConstantsRector

Phần tiêu đề “DowngradeTraitConstantsRector”

Chuyển các hằng số của trait thành thuộc tính tĩnh. Các runtime cũ hơn từ chối hằng số trong trait với thông báo “Traits cannot have constants”. Quy tắc cũng viết lại các tham chiếu self::CONST và static::CONST sang dạng thuộc tính tĩnh. Quyền hiển thị được giữ nguyên; bộ điều chỉnh final bị loại bỏ vì thuộc tính không thể là final trên các mục tiêu cũ hơn. Một hằng số lớp có kiểu sẽ trở thành một thuộc tính có kiểu. Biến đổi này dựa trên mã nguồn từ 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;
    }
}

Quy trình hai lượt cho PHP 7.4

Phần tiêu đề “Quy trình hai lượt cho PHP 7.4”

Mục tiêu PHP 7.4 không thể chạy chỉ trong một lượt. Bộ phân giải giá trị tham số mặc định của Rector bị lỗi với các giá trị mặc định của enum case trong constructor promotion. Vì vậy script build chạy:

  1. Lượt 1 — tiền xử lý enum. rector-php74-enums.php chỉ chạy quy tắc tích hợp để chuyển enum thành lớp danh sách hằng số. Sau lượt này, các enum case trở thành hằng số lớp thông thường.
  2. Xóa cache. Cache của Rector được xóa để lượt thứ hai không nhìn thấy cây cú pháp cũ.
  3. Các bước sửa chữa hậu xử lý. scripts/build.php viết lại những mẫu mà quy tắc chuyển enum thành lớp không xử lý. Các phương thức instance cũ của enum trở thành tĩnh. Các truy cập EnumClass::Case->value và ->name được phân giải. Các đối số có tên mà Rector không thể gắn kết sẽ được làm phẳng thành đối số theo vị trí. Nếu không, các mẫu cú pháp này sẽ gây lỗi phân tích cú pháp trên PHP 7.4.
  4. Lượt 2 — hạ cấp toàn bộ. rector-php74.php chạy toàn bộ chuỗi hạ cấp PHP 7.4 cùng với các quy tắc tùy chỉnh.

Đã đối chiếu với scripts/build.php (runRector(), postProcessFixups()).

Tham chiếu cờ build

Phần tiêu đề “Tham chiếu cờ build”

scripts/build.php điều phối quá trình build. Các tùy chọn của script được đối chiếu với lệnh gọi getopt() và constructor Build:

CờMặc địnhTác động
--version=<x.y.z>2.0.0Phiên bản được ghi vào hai tệp được tạo ra: composer.json và CHANGELOG.md
--source-dir=<path>c:/Users/admin/DocumentsThư mục gốc chứa các kho mã nguồn ngang hàng
--output-dir=<path><repo>/outputNơi ghi bản phân phối được tạo ra
--target=php74 | --target=php81php81Mục tiêu hạ cấp. php74 buộc chỉ dùng core và tắt Pro
--dry-runtắtChạy mọi giai đoạn ở chế độ chỉ báo cáo; bước sao chép và Rector được bỏ qua
--no-protắtLoại trừ gói Pro (chỉ với mục tiêu PHP 8.1; PHP 7.4 đã loại trừ nó rồi)

Giá trị --target không hợp lệ sẽ phát sinh InvalidArgumentException trước khi bất kỳ công việc nào bắt đầu. Đã đối chiếu với Build::__construct() (bộ bảo vệ VALID_TARGETS).

Các script Composer

Phần tiêu đề “Các script Composer”
ScriptLệnhMục đích
composer testphpunitChạy các bộ fixture của quy tắc
composer analysephpstan analyse rector/rules scripts --level=10Phân tích tĩnh mã build
composer buildphp scripts/build.phpBuild đầy đủ
composer build:dryphp scripts/build.php --dry-runChạy build thử (dry-run)

Đã đối chiếu với composer.jsonscripts.

Tiếp theo

Phần tiêu đề “Tiếp theo”
  • /integrations/backport/quickstart/ — chạy build thử và build đầy đủ.
  • /integrations/backport/troubleshooting/ — ý nghĩa của từng giai đoạn thất bại.