Tổng quan về NextPDF Backport Builder

Đây là công cụ build, không phải phụ thuộc khi chạy. Người bảo trì NextPDF dùng gói này để tạo các bản phân phối NextPDF tương thích với PHP 8.1+ và PHP 7.4+. Ứng dụng không bao giờ được thêm gói này như một phụ thuộc khi chạy.

Tổng quan nhanh

NextPDF Backport Builder là hạ tầng build dùng để tạo bản phân phối backport của hệ sinh thái NextPDF cho các runtime PHP cũ hơn mốc cơ sở phát triển. NextPDF được viết cho một phiên bản PHP hiện đại và dùng cú pháp mà các trình thông dịch cũ hơn sẽ từ chối. Builder đưa mã nguồn qua Rector, một engine biến đổi cây cú pháp trừu tượng, rồi xuất ra các gói có cú pháp mà runtime PHP 8.1 hoặc PHP 7.4 chấp nhận.

Tên gói Composer là nextpdf/backport-builder. Gói này khai báo "type": "project" và không mang theo bất kỳ phụ thuộc khi chạy nào của NextPDF. Các yêu cầu của nó chỉ giới hạn ở engine build (rector/rector), phân tích tĩnh (phpstan/phpstan), trình chạy test (phpunit/phpunit), và một tập các gói symfony/polyfill-* được dùng trong đầu ra được tạo. composer.json ở gốc kho lưu trữ xác minh điều này.

Gói này không phải là gì

Kho lưu trữ này không chứa engine NextPDF. Nó chứa các quy tắc và script để biến đổi engine đó thành dạng đã backport. Sự tách biệt này có ba tác động thực tế:

• Bạn không cài đặt gói này để kết xuất PDF. Hãy cài đặt nextpdf/backport, sản phẩm do builder này tạo ra. Hãy đặt builder 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).
• Bạn không phát triển dựa trên mã được tạo. Bản phân phối được tạo là sản phẩm chỉ đọc do máy sinh ra. Hãy gửi báo cáo lỗi và yêu cầu tính năng đến các kho mã nguồn nextpdf/* gốc.
• Đầu ra được phát hành dưới dạng tag phiên bản, không phải dưới dạng nhánh của kho lưu trữ này. Pipeline phát hành gắn tag cho cây được tạo và đính kèm các tệp lưu trữ vào một bản phát hành GitHub.

Nó tạo ra những gì

Builder xuất ra các gói Composer có tên và giấy phép do scripts/adjust-composer.php cố định:

Gói được tạo ra	Giấy phép	Phạm vi	Được build khi
nextpdf/backport	Apache-2.0	Core, các adapter framework và lớp tương thích tcpdf cho mục tiêu PHP 8.1	Luôn luôn
nextpdf/backport-pro	proprietary	Mô-đun Pro, được xuất dưới dạng một gói riêng	Mục tiêu PHP 8.1, khi có mã nguồn Pro và Pro không bị loại trừ

Gói nextpdf/backport khai báo các mục replace của Composer để sau khi cài đặt, nó đáp ứng các ràng buộc của gói gốc. Với mục tiêu PHP 8.1, các gói được thay thế là nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter, và nextpdf/compat-legacy. Với mục tiêu PHP 7.4, chỉ nextpdf/core được thay thế vì bản build PHP 7.4 chỉ gồm core. scripts/adjust-composer.php (buildReplace()) xác minh điều này.

Autoloader của bên tiêu dùng phân giải cây đã hợp nhất qua tiền tố PHP Standards Recommendation 4 (PSR-4), NextPDF\, ánh xạ tới src/. PSR-4 ánh xạ tiền tố namespace tới thư mục cơ sở và phân giải từng tên lớp đầy đủ thành một tệp bên dưới thư mục đó; xem PHP Framework Interop Group (PHP-FIG) PSR-4. Gói Pro ánh xạ NextPDF\Pro\ tới src/ riêng của nó.

Ma trận PHP được hỗ trợ

Ma trận bên dưới chỉ bao gồm những gì các cấu hình Rector và script build áp đặt. Máy chủ build luôn chạy một phiên bản PHP hiện đại. Đầu ra nhắm đến một phiên bản cũ hơn.

Khía cạnh	Giá trị	Bằng chứng
PHP của máy chủ build	>=8.4 <9.0	composer.jsonrequire.php
PHP build/test trong CI	8.5	.github/workflows/0-ci.yml, build.yml (shivammathur/setup-phpphp-version: '8.5')
Ràng buộc đầu ra của mục tiêu PHP 8.1	>=8.1 <8.5	scripts/adjust-composer.php (generatePublicComposer())
Ràng buộc đầu ra của mục tiêu PHP 7.4	>=7.4 <8.1	scripts/adjust-composer.php (generatePublicComposer())
Phạm vi của mục tiêu PHP 8.1	Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, riêng biệt)	scripts/merge-sources.php, scripts/adjust-composer.php
Phạm vi của mục tiêu PHP 7.4	Chỉ core	scripts/build.php (--target=php74 buộc chỉ build core, Pro bị tắt)

Bản build PHP 8.1 được kiểm định trên PHP 8.1, 8.2, 8.3 và 8.4. Bản build PHP 7.4 được kiểm định trên PHP 7.4 và 8.0. Các ma trận công việc validate-php81 và validate-php74 trong .github/workflows/build.yml xác minh điều này. Đây là các runtime mà pipeline kiểm thử. Đó là tập kiểm định đã quan sát được, không phải tuyên bố về tính tuân thủ.

Mô hình hai nhánh

Kho lưu trữ này không có nhánh main. PHP74 là nhánh mặc định, còn PHP81 là nhánh cố định thứ hai. Nhánh của bạn quyết định hai điều: mục tiêu mặc định của bản build cục bộ và tập mã nguồn được hợp nhất. Hãy áp dụng các thay đổi ảnh hưởng đến cả hai mục tiêu vào từng nhánh thông qua pull request riêng cho nhánh đó. Workflow CI chạy trên cả PHP74 và PHP81. Điều này được xác minh dựa trên git branch -a và .github/workflows/0-ci.yml (branches: [PHP74, PHP81]).

Một bản phát hành diễn ra như thế nào

Quy trình phát hành được điều khiển theo sự kiện. Khi tổ chức mã nguồn NextPDF phát hành một release tag, sự kiện repository-dispatch loại source-release sẽ kích hoạt workflow build. Workflow checkout từng kho mã nguồn tại tag tương ứng, chạy pipeline, kiểm tra cú pháp đầu ra trên runtime mục tiêu, kiểm định đầu ra trên toàn bộ ma trận hỗ trợ, và đính kèm các tệp lưu trữ vào một bản phát hành GitHub. Tag phiên bản tuân theo Semantic Versioning: số phiên bản có dạng MAJOR.MINOR.PATCH trên một API công khai đã khai báo (Semantic Versioning 2.0.0 §2). .github/workflows/build.yml xác minh điều này.

Đi đâu tiếp theo

• /integrations/backport/install/ — cách cài đặt builder trên máy chủ build, và cách các bên tiêu dùng cài đặt gói được tạo.
• /integrations/backport/configuration/ — các cấu hình Rector, quy tắc tùy chỉnh, và cờ build.
• /integrations/backport/quickstart/ — một lần chạy thử dựa trên mã nguồn và lệnh build đầy đủ.
• /integrations/backport/production-usage/ — cách tích hợp builder vào một workflow phát hành.
• /integrations/backport/troubleshooting/ — các dạng lỗi mà pipeline phòng ngừa và cách đọc hiểu chúng.
• /integrations/backport/security-and-operations/ — tư thế chuỗi cung ứng, ranh giới tin cậy, và các đảm bảo vận hành.
• /integrations/backport/boot-and-discovery/ — cách builder khám phá các mô-đun nguồn và khởi động.
• /integrations/backport/integration/ — hợp đồng tích hợp trên máy chủ build.