Khởi động và khám phá NextPDF backport

Công cụ build — KHÔNG phải là phần phụ thuộc thời gian chạy. Trang này giải thích cách trình build khởi động trên máy chủ của người bảo trì hoặc máy chủ tích hợp liên tục (CI). Ứng dụng backend không bao giờ tải mã này.

Tổng quan nhanh

Trình build không dùng framework, dependency injection container hay cơ chế tự động khám phá service provider. Thay vào đó, các script giao diện dòng lệnh (CLI) PHP được nối với nhau bằng require_once và trình autoload PSR-4 của Composer. Ở đây, “khám phá” có hai nghĩa cụ thể: giai đoạn merge đọc những repository nguồn nào, và trình điều phối chọn cấu hình Rector cho target ra sao.

Tổng quan về pipeline build

Trình điều phối là scripts/build.php. Nó khởi chạy quá trình build, rồi lần lượt chạy năm giai đoạn. Mỗi giai đoạn đều có gate kiểm tra, vì vậy lỗi đầu tiên sẽ dừng toàn bộ quá trình build:

1. Merge sources — sao chép các repository nguồn vào một cây chung.
2. Run Rector downgrade — chạy một lượt cho PHP 8.1; chạy hai lượt kèm các bước chỉnh sửa bổ sung cho PHP 7.4.
3. Generate composer.json — ghi manifest của gói được tạo cùng với bản đồ replace.
4. Copy static assets — sao chép giấy phép và changelog được tạo ra.
5. Validate output — đếm số tệp PHP đã tạo; gate kiểm tra cú pháp chính thức sẽ chạy sau đó trong CI.

Đã xác minh qua scripts/build.php (run(), step()). Xem /integrations/backport/configuration/ để biết chi tiết về cách chọn quy tắc và /integrations/backport/production-usage/ để biết về gate kiểm tra CI.

Khám phá các module nguồn

Khâu khám phá nguồn không dựa trên manifest. scripts/merge-sources.php dùng một bản đồ cố định, được lập chỉ mục theo tên repository và chọn theo target.

Đối với target PHP 8.1, bản đồ bao gồm nextpdf (core), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, và nextpdf-Pro khi bao gồm Pro. Đối với target PHP 7.4, bản đồ thu gọn lại chỉ còn nextpdf. Trình build phân giải mỗi repository thành một thư mục cùng cấp nằm dưới thư mục gốc --source-dir. Nó kiểm tra mọi repository dự kiến trước khi sao chép bất cứ thứ gì. Nếu thiếu một repository, quá trình merge sẽ hủy bỏ và báo cáo tên cùng đường dẫn tương ứng. Đã xác minh qua scripts/merge-sources.php (MergeSources::__construct(), run()).

Quá trình merge đặt core tại src/ và đặt mỗi adapter dưới thư mục con theo namespace tương ứng (src/Artisan/, src/Laravel/, và cứ thế). Pro được đặt vào một cây pro/src/ riêng để quá trình build có thể xuất nó thành gói riêng. Đã xác minh qua MergeSources (mergeCore(), mergeArtisan(), mergePro()).

Trình tự khởi động

1. scripts/build.php chạy trong Giao diện lập trình ứng dụng máy chủ (SAPI) CLI. Nó require_once các tệp merge-sources.php và adjust-composer.php.
2. Điểm vào CLI đọc các tùy chọn bằng getopt() — --version, --source-dir, --output-dir, --target, --dry-run, --no-pro.
3. Một instance Build được khởi tạo. Hàm khởi tạo kiểm tra --target với ['php74', 'php81'] và ném ra InvalidArgumentException cho giá trị không hợp lệ trước khi bất kỳ công việc nào bắt đầu. Đối với target PHP 7.4, nó buộc đầu ra chỉ gồm core và vô hiệu hóa Pro.
4. Build::run() thực thi năm giai đoạn và thoát với mã trạng thái 0 khi thành công, hoặc 1 khi gặp lỗi đầu tiên.

Đã xác minh qua scripts/build.php (điểm vào CLI, Build::__construct(), run()).

Kết nối container

Không áp dụng. Trình build là một công cụ CLI. Nó không có dependency injection container và cũng không có service container của framework. Cách kết nối dựa vào các lệnh gọi require_once tường minh, cùng với tính năng autoload PSR-4 của Composer cho NextPDF\Backport\ (rules) và NextPDF\Backport\Scripts\ (scripts). Đã xác minh qua composer.jsonautoload và các câu lệnh require_once trong scripts/build.php.

Thứ tự phân giải cấu hình

Không có tệp cấu hình. Cấu hình đến từ các cờ CLI, được phân giải theo các giá trị mặc định tích hợp sẵn trong script:

1. Cờ CLI, nếu được cung cấp.
2. Giá trị mặc định trong khối phân tích cú pháp getopt() (ví dụ, target mặc định là php81, và phiên bản mặc định là 2.0.0).
3. Hành vi mà hàm khởi tạo suy ra từ target (PHP 7.4 buộc chỉ dùng core và không có Pro, bất kể --no-pro).

Đã xác minh qua scripts/build.php (điểm vào CLI và Build::__construct()). Tài liệu tham chiếu đầy đủ về các cờ nằm trong /integrations/backport/configuration/.

Chẩn đoán

Trình điều phối có phần chẩn đoán riêng. Chạy chế độ thử (composer build:dry) để in ra các repository nguồn sẽ được đọc và mục đích của từng giai đoạn, nhưng không ghi bất cứ thứ gì. Mỗi giai đoạn in ra một dấu kiểm thành công hoặc một lỗi có tên cụ thể. Không có lệnh con chẩn đoán riêng và không có điểm vào bin/. Trình build chạy thông qua scripts/build.php hoặc các bí danh Composer-script của nó. Đã xác minh qua scripts/build.php (step(), các nhánh dryRun), scripts/merge-sources.php (đường dẫn dry-run của run()), và composer.jsonscripts.

Xem thêm

• /integrations/backport/overview/ — trình build là gì và nó tạo ra những gì.
• /integrations/backport/integration/ — hợp đồng tích hợp với máy chủ build.
• /integrations/backport/configuration/ — các cấu hình Rector và tài liệu tham chiếu về cờ.
• /integrations/backport/troubleshooting/ — tài liệu tham khảo về lỗi theo từng giai đoạn.