Khắc phục sự cố NextPDF Backport Builder

Công cụ build — KHÔNG phải là một phụ thuộc runtime. Mọi triệu chứng trên trang này đều là điều kiện tại thời điểm build trên máy chủ của người bảo trì hoặc máy chủ continuous integration (CI). Không có điều kiện nào trong số này xuất hiện trong ứng dụng downstream.

Tổng quan nhanh

Quá trình build chạy tuần tự qua năm giai đoạn. Nó dừng ở lỗi đầu tiên và in ra tên giai đoạn kèm thông báo. Hãy đọc tên giai đoạn, rồi tra nguyên nhân tương ứng bên dưới. Các giai đoạn gồm gộp nguồn, chạy hạ cấp Rector, tạo composer.json, sao chép tài nguyên tĩnh và kiểm tra đầu ra. Đã kiểm chứng với scripts/build.php (run() và step()).

Giai đoạn: gộp nguồn

”Source repo '' not found at: ”

Quá trình gộp sẽ kiểm tra mọi kho nguồn dự kiến trước khi sao chép tệp. Nếu thiếu một kho, quá trình build sẽ hủy và in ra tên cùng đường dẫn của kho đó. Mục tiêu PHP 8.1 cần có nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, và — khi bao gồm Pro — nextpdf-Pro. Mục tiêu PHP 7.4 chỉ cần nextpdf. Đã kiểm chứng với scripts/merge-sources.php (vòng lặp kiểm tra run(), bản đồ kho __construct()).

Cách khắc phục: kiểm xuất các kho vào những thư mục cùng cấp bên dưới đường dẫn truyền cho --source-dir, và dùng đúng các tên thư mục ở trên. Một lần chạy thử (dry run) sẽ liệt kê mọi kho mà nó sẽ đọc. Hãy dùng lần chạy này để xác nhận bố cục trước khi chạy một bản build đầy đủ.

Giai đoạn: chạy hạ cấp Rector

Rector thoát với mã khác 0

Bộ điều phối báo cáo Rector failed on <label> (exit code: N) rồi dừng lại. Nhãn này cho biết lượt nào thất bại: public package, pro package, enum pre-processing, hoặc full downgrade. Đã kiểm chứng với scripts/build.php (runRectorPass()).

Bộ giải mặc định tham số bị sập với các giá trị mặc định là enum (PHP 7.4)

Đây là lý do mục tiêu PHP 7.4 dùng hai lượt. Bộ giải giá trị mặc định của tham số trong Rector bị sập khi một enum case được dùng làm giá trị mặc định cho constructor promotion. Lượt 1 (rector-php74-enums.php) chuyển đổi các enum thành lớp danh sách hằng số trước. Nhờ vậy, lượt đầy đủ ở Lượt 2 sẽ không bao giờ gặp giá trị mặc định là enum case. Nếu bỏ qua bộ điều phối và chạy trực tiếp cấu hình PHP 7.4 đầy đủ trên mã nguồn có chứa enum, hãy lường trước lỗi sập này. Đã kiểm chứng với scripts/build.php (chú thích runRector() và trình tự hai lượt) và rector/config/rector-php74-enums.php.

Các script benchmark làm sập Rector

rector-php81.php và rector-php74.php bỏ qua */tests/Benchmark/*. Những script đó tham chiếu đến các thư viện Portable Document Format (PDF) bên ngoài mà Rector không thể giải, khiến bộ giải mặc định tham số bị sập. Nếu một đường dẫn benchmark vẫn bị xử lý, mẫu glob bỏ qua đang thiếu hoặc đường dẫn đã khác đi. Đã kiểm chứng với các lệnh gọi withSkip().

`MHASH_XXH*` gây lỗi sập (PHP 7.4)

rector-php74.php bỏ qua DowngradeHashAlgorithmXxHashRector. Quy tắc tích hợp sẵn đó bị sập với các hằng số xxHash. Mã nguồn không dùng xxHash, nên có thể bỏ qua an toàn. Đã kiểm chứng với rector/config/rector-php74.php (withSkip()).

Giai đoạn: chỉnh sửa sau Rector (chỉ PHP 7.4)

Các bước chỉnh sửa chạy giữa hai lượt. Chúng viết lại những mẫu còn sót lại từ quy tắc chuyển enum thành lớp. Nếu đầu ra PHP 7.4 gặp lỗi phân tích cú pháp liên quan đến EnumClass::Case->value, ->name, một phương thức enum cũ được gọi như phương thức thể hiện, hoặc một đối số có tên trên một kiểu chưa được giải, thì bước chỉnh sửa đã không khớp với mẫu đó. Hạn chế của clone-with cũng áp dụng ở đây: việc khớp đối số không đệ quy, nên một giá trị ghi đè có ngoặc đơn lồng nhau sẽ không được viết lại. Đã kiểm chứng với scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) và rector/rules/DowngradeCloneWithRector.php (hạn chế đã ghi nhận).

Giai đoạn: tạo composer.json

Giai đoạn này di chuyển các thư mục src/ và tests/ đã xử lý từ thư mục build-temp sang thư mục đầu ra. Sau đó nó ghi composer.json đã được tạo. Lỗi ở đây hầu như luôn là điều kiện hệ thống tệp: thư mục đầu ra không ghi được, hoặc cây build-temp bị thiếu vì Rector không tạo ra gì cả. Đã kiểm chứng với scripts/build.php (adjustComposer(), moveTree()).

Giai đoạn: sao chép tài nguyên tĩnh

Giai đoạn này sao chép LICENSE từ kho nguồn core và ghi một CHANGELOG.md đã được tạo. Nếu không có LICENSE, bước sao chép sẽ bị bỏ qua một cách lặng lẽ và quá trình build vẫn tiếp tục; changelog thì luôn được ghi. Lỗi ở đây nghĩa là thư mục đầu ra đã trở nên không ghi được giữa chừng quá trình build. Đã kiểm chứng với scripts/build.php (copyStaticAssets()).

Giai đoạn: kiểm tra đầu ra

Lỗi xác thực đầu ra: “Output src/ directory not found” và “No PHP files found in output”

Việc kiểm tra yêu cầu output/src không rỗng. Một cây rỗng nghĩa là quá trình gộp không sao chép gì, hoặc việc di chuyển tệp đã thất bại. Đã kiểm chứng với scripts/build.php (validateOutput()).

”Syntax validation: skipped (requires PHP runtime)”

Đây là điều bình thường, không phải lỗi. Máy chủ build chạy PHP hiện đại, không phải runtime mục tiêu, nên giai đoạn cục bộ chỉ đếm tệp và in ra lệnh Docker để thực hiện kiểm tra cú pháp thực sự. Cổng cú pháp chính thức là bước php -l sau khi build trong quy trình phát hành, chạy trên đúng runtime mục tiêu thực tế. Đã kiểm chứng với scripts/build.php (validateOutput()) và .github/workflows/build.yml (các bước kiểm tra cú pháp PHP 8.1 / PHP 7.4).

Các hạn chế đã biết

Những hạn chế này là cố hữu trong cách tiếp cận hạ cấp. Chúng đã được kiểm chứng với các quy tắc và mục “Known Limitations” trong README.md của dự án:

Các thuộc tính readonly bị loại bỏ. Quá trình build loại bỏ readonly để phần mở rộng clone-with có thể gán thuộc tính một cách tường minh trên runtime cũ hơn. Đầu ra đã hạ cấp không còn được runtime đảm bảo tính bất biến nữa.
#[Override] không được thực thi trên PHP 8.1. Thuộc tính (attribute) này có thể vẫn còn, nhưng runtime cũ hơn không xử lý nó.
Mục tiêu PHP 7.4 chỉ có core. Các adapter framework, lớp tương thích tcpdf và Pro bị loại khỏi bản phân phối PHP 7.4 theo thiết kế của script build.
Pro là một gói riêng và chỉ dành cho PHP 8.1. Không có bản build Pro cho PHP 7.4.
Việc khớp đối số của clone-with không đệ quy. Các giá trị ghi đè có chứa ngoặc đơn lồng nhau sẽ không được biến đổi, và chỉ các khóa mảng kiểu chuỗi mới được giải thành tên thuộc tính.

/integrations/backport/configuration/ — tài liệu tham khảo về quy tắc và cờ.
/integrations/backport/production-usage/ — cổng CI và luồng phát hành.