Tham khảo API Backport Builder
Tổng quan nhanh
Phần tiêu đề “Tổng quan nhanh”Backport Builder là công cụ build, không phải thư viện runtime. Giao diện công khai của nó gồm các lệnh build (scripts/build.php và các wrapper composer build* của nó), bốn lớp cấp script đứng phía sau (Build, MergeSources, AdjustComposer, ValidateBuildContract), ba tệp cấu hình Rector, ba quy tắc Rector tùy chỉnh, và hợp đồng gói được tạo ra (nextpdf/backport và nextpdf/backport-pro). Hãy chạy nó trên máy build hoặc môi trường tích hợp liên tục (CI) để chuyển mã nguồn NextPDF hiện đại thành bản phân phối đã hạ cấp. Tuyệt đối không thêm nó vào một ứng dụng.
Nếu mới bắt đầu, hãy dùng composer build:dry (lệnh này phân giải thành php scripts/build.php --dry-run). Lệnh này chạy thử mọi giai đoạn ở chế độ chỉ báo cáo mà không ghi tệp, nhờ đó bạn có thể xác nhận bố cục mã nguồn và các cờ trước khi build thật. Ví dụ đầu tiên trong “Tác vụ thường gặp” cũng dùng chính lệnh này.
Tác vụ thường gặp
Phần tiêu đề “Tác vụ thường gặp”Trường hợp dùng phổ biến nhất của gói này là chạy build trên máy build. Mỗi ví dụ bên dưới là một lệnh đơn, đã được kiểm chứng với scripts/build.php và composer.json.
Kiểm tra pipeline mà không ghi bất kỳ thứ gì (lần chạy đầu an toàn):
composer build:dryLệnh này phân giải thành php scripts/build.php --dry-run. Nó chạy bước hợp nhất, Rector, tạo composer, sao chép tài nguyên và kiểm tra ở chế độ chỉ báo cáo, nhưng không sao chép gì cả.
Tạo bản phân phối PHP 8.1 đầy đủ (nextpdf/backport, kèm theo nextpdf/backport-pro khi có mã nguồn Pro):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./outputLệnh này hợp nhất core, các adapter framework và lớp tương thích tcpdf. Nó chạy một lượt Rector duy nhất cho mục tiêu PHP 8.1 rồi ghi cây gói được tạo ra vào ./output. Thêm --no-pro để bỏ qua gói Pro.
Tạo bản phân phối PHP 7.4 chỉ gồm core (pipeline enum hai lượt):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./output-php74 \ --target=php74--target=php74 buộc kết quả chỉ gồm core, vô hiệu hóa Pro, đồng thời chạy bước tiền xử lý enum, bước chỉnh sửa sau Rector và lượt hạ cấp PHP 7.4 đầy đủ.
Bề mặt lệnh
Phần tiêu đề “Bề mặt lệnh”Dùng bảng này khi cần tra cứu chữ ký, cờ và hành vi thoát chính xác của các điểm vào build cùng các lớp cấp script điều khiển một lần build.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
scripts/build.php | Mục tiêu, phiên bản, đường dẫn nguồn, đường dẫn đầu ra và các cờ như được mô tả trong script. | Dùng mặc định mục tiêu theo từng nhánh. | Cây gói được tạo ra. | Thoát với mã khác 0 và xuất lỗi theo từng giai đoạn. | Điểm vào build chính. Chạy trên máy build, không chạy trong ứng dụng. |
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false) | Phiên bản, thư mục nguồn, thư mục đầu ra, làn runtime mục tiêu, cờ bao gồm Pro, cờ dry-run. | Nhắm tới PHP 8.1, bao gồm Pro trừ trường hợp PHP 7.4, và ghi tệp trừ khi bật dry-run. | Build | InvalidArgumentException khi mục tiêu không được hỗ trợ; lỗi theo giai đoạn trong run(). | Lớp cấp script đứng sau scripts/build.php. |
Build::run() | không có. | Kiểm tra hợp đồng, hợp nhất nguồn, điều chỉnh metadata của composer.json, và chạy các lượt Rector. | bool | Trả về false với các lỗi giai đoạn dự kiến; có thể ném lỗi hệ thống tệp hoặc runtime không lường trước. | CI nên thất bại khi gặp false. |
composer build:dry | Wrapper script của Composer. | Kiểm tra build dry-run. | Trạng thái thoát và log. | Thoát với mã khác 0 khi build hoặc kiểm tra thất bại. | Được các cổng CI sử dụng. |
scripts/merge-sources.php | Các đường dẫn checkout nguồn và mục tiêu hợp nhất. | Hợp nhất các gói nguồn đã chọn cho runtime mục tiêu. | Cây nguồn đã hợp nhất. | Thiếu nguồn, mục tiêu không được hỗ trợ, lỗi hệ thống tệp. | Giữ các ref nguồn khớp với release tag. |
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false) | Thư mục gốc chứa nguồn, thư mục đầu ra, cờ bao gồm Pro, cờ dry-run, cờ chỉ core. | Hợp nhất tất cả các repository đã cấu hình, hoặc chỉ core khi coreOnly là true. | MergeSources | Đường dẫn nguồn hoặc đầu ra không hợp lệ trong khi chạy. | Lớp cấp script đứng sau scripts/merge-sources.php. |
MergeSources::run() | không có. | Sao chép và chuẩn hóa các cây nguồn đã chọn vào mục tiêu build. | bool | Trả về false với các lỗi hợp nhất dự kiến. | Có thể đọc log bằng getLog(). |
MergeSources::getLog() | không có. | Trả về các mục log giai đoạn đã tích lũy. | array | không có dự kiến. | Dùng để chẩn đoán CI. |
scripts/adjust-composer.php | Metadata và phiên bản của composer.json được tạo ra. | Ghi các ràng buộc gói và các mục replace cho kết quả được tạo ra. | Đã điều chỉnh composer.json. | Phiên bản không hợp lệ hoặc thiếu tệp được tạo ra. | Quản lý danh tính gói được tạo ra. |
AdjustComposer::__construct(string $version, string $target = 'php81') | Chuỗi phiên bản và làn mục tiêu. | Mục tiêu PHP 8.1. | AdjustComposer | Lỗi mục tiêu không hợp lệ trong các đường dẫn tạo gói. | Được các script build và test sử dụng. |
AdjustComposer::generatePublicComposer() | không có. | Tạo metadata cho nextpdf/backport. | array | không có dự kiến. | API tạo gói thuần túy dành cho test. |
AdjustComposer::generateProComposer() | không có. | Tạo metadata cho nextpdf/backport-pro. | array | không có dự kiến. | API tạo gói thuần túy cho làn build độc quyền. |
AdjustComposer::writePublicComposer(string $outputDir) | Thư mục đầu ra. | Ghi composer.json công khai được tạo ra. | void | Lỗi hệ thống tệp. | Chỉ dùng trong các thư mục đầu ra được tạo ra. |
AdjustComposer::writeProComposer(string $proOutputDir) | Thư mục đầu ra Pro. | Ghi composer.json Pro được tạo ra. | void | Lỗi hệ thống tệp. | Yêu cầu cây đầu ra Pro phải tồn tại. |
ValidateBuildContract::__construct(string $repoRoot) | Thư mục gốc của repository. | Dùng thư mục gốc repository được cung cấp làm cơ sở hợp đồng. | ValidateBuildContract | không có dự kiến. | Bộ kiểm tra hợp đồng cấp script. |
ValidateBuildContract::run() | không có. | Kiểm tra các đầu vào bắt buộc và giả định build. | bool | Trả về false khi hợp đồng thất bại. | Chạy trước khi tin cậy kết quả build. |
Cấu hình Rector
Phần tiêu đề “Cấu hình Rector”Dùng bảng này để xem tệp cấu hình Rector nào điều khiển từng làn mục tiêu, và từng lượt nằm ở đâu trong pipeline một lượt của PHP 8.1 hoặc hai lượt của PHP 7.4.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
rector/config/rector-php81.php | Cây nguồn và runtime của Rector. | Hạ cấp một lượt xuống mục tiêu PHP 8.1. | Mã nguồn đã biến đổi. | Lỗi phân tích hoặc biến đổi của Rector. | Dùng cho làn phân phối PHP 8.1. |
rector/config/rector-php74-enums.php | Cây nguồn và runtime của Rector. | Lượt PHP 7.4 đầu tiên để chuyển đổi enum. | Mã nguồn trung gian đã biến đổi. | Lỗi phân tích hoặc biến đổi của Rector. | Chạy trước lượt PHP 7.4 đầy đủ. |
rector/config/rector-php74.php | Mã nguồn trung gian và runtime của Rector. | Lượt hạ cấp PHP 7.4 đầy đủ. | Mã nguồn tương thích PHP 7.4. | Lỗi phân tích hoặc biến đổi của Rector. | Dùng cho làn phân phối PHP 7.4. |
Quy tắc tùy chỉnh
Phần tiêu đề “Quy tắc tùy chỉnh”Dùng bảng này khi bảo trì hoặc mở rộng ba quy tắc Rector riêng của dự án và cần biết hợp đồng phương thức của từng quy tắc cùng cú pháp mà quy tắc đó biến đổi.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
DowngradeAsymmetricVisibilityRector | Các thuộc tính hoặc tham số được nâng cấp dùng visibility bất đối xứng. | Visibility thông thường tương thích với các runtime cũ hơn. | Giữ lại read visibility khi có thể. | Lỗi quy tắc Rector. | Các hạn chế setter chỉ tồn tại ở thời điểm biên dịch và bị loại bỏ trong kết quả được tạo ra. |
DowngradeAsymmetricVisibilityRector::getRuleDefinition() | không có. | Trả về metadata và ví dụ của quy tắc Rector. | RuleDefinition | không có dự kiến. | Giữ tài liệu quy tắc hiển thị với công cụ Rector. |
DowngradeAsymmetricVisibilityRector::getNodeTypes() | không có. | Chọn các kiểu node mà quy tắc kiểm tra. | array<class-string<Node>> | không có dự kiến. | Phạm vi nên giữ hẹp để các biến đổi mang tính tất định. |
DowngradeAsymmetricVisibilityRector::refactor(Node $node) | Node AST. | Chuyển đổi visibility bất đối xứng tại những nơi xuất hiện. | `Node | null` | Lỗi quy tắc Rector. |
DowngradeCloneWithRector | clone() kèm theo ghi đè thuộc tính. | Clone cộng với các phép gán thuộc tính tường minh. | Dùng các biến tạm được tạo ra. | Lỗi quy tắc Rector. | Phải chạy sau các bước hạ cấp thuộc tính readonly. |
DowngradeCloneWithRector::getRuleDefinition() | không có. | Trả về metadata và ví dụ của quy tắc. | RuleDefinition | không có dự kiến. | Được công cụ chẩn đoán của Rector sử dụng. |
DowngradeCloneWithRector::getNodeTypes() | không có. | Chọn các node return và expression. | array<class-string<Node>> | không có dự kiến. | Giữ quy tắc tập trung vào cú pháp clone-with. |
DowngradeCloneWithRector::refactor(Node $node) | Node AST. | Viết lại clone-with thành clone cộng với các phép gán. | `array | null` | Lỗi quy tắc Rector. |
DowngradeTraitConstantsRector | Các hằng số trait và các tham chiếu tới chúng. | Các thuộc tính tĩnh và các tham chiếu thuộc tính. | Giữ lại visibility khi có thể. | Lỗi quy tắc Rector. | Loại bỏ final vì các thuộc tính cũ hơn không thể là final. |
DowngradeTraitConstantsRector::getRuleDefinition() | không có. | Trả về metadata và ví dụ của quy tắc. | RuleDefinition | không có dự kiến. | Được công cụ chẩn đoán của Rector sử dụng. |
DowngradeTraitConstantsRector::getNodeTypes() | không có. | Chọn các node trait và class-constant-fetch. | array<class-string<Node>> | không có dự kiến. | Giữ quy tắc giới hạn ở các hằng số trait. |
DowngradeTraitConstantsRector::refactor(Node $node) | Node AST. | Viết lại các hằng số trait và tham chiếu tới chúng thành các thuộc tính tương thích. | `Node | null` | Lỗi quy tắc Rector. |
Hợp đồng gói được tạo ra
Phần tiêu đề “Hợp đồng gói được tạo ra”Dùng bảng này để xem builder phát ra những gì: tên các gói mà dự án phía sau cài đặt và gói chứa bản phân phối Pro.
| Gói được tạo ra | Vai trò runtime | Ghi chú |
|---|---|---|
nextpdf/backport | Bản phân phối runtime mã nguồn mở được tạo ra. | Thay thế các gói nextpdf/* đã chọn cho runtime mục tiêu. |
nextpdf/backport-pro | Bản phân phối Pro độc quyền được tạo ra khi có mã nguồn Pro. | Được phát hành riêng với gói mã nguồn mở. |
Ghi chú phát triển
Phần tiêu đề “Ghi chú phát triển”- Builder tiêu thụ các bản phát hành mã nguồn và phát ra các artifact được tạo ra. Đừng vá kết quả được tạo ra như thể đó là nguồn chân lý.
- Mỗi quy tắc tùy chỉnh phải có fixture test trước khi được đưa vào pipeline build.
- Các job phát hành phải kiểm tra kết quả được tạo ra trên runtime mục tiêu, không chỉ trên máy build.