Cài đặt NextPDF Backport Builder

Hãy cài đặt bộ công cụ build này trên máy trạm của người bảo trì hoặc trên runner tích hợp liên tục (CI). Đây KHÔNG phải là dependency runtime. Ứng dụng phía sau không bao giờ cài đặt builder; ứng dụng đó cài đặt gói do builder tạo ra.

Tổng quan nhanh

Hai nhóm đối tượng sẽ cài đặt các thành phần khác nhau:

Một người bảo trì hoặc người vận hành CI clone repository này và cài đặt các dependency build của nó. Chỉ cài đặt nextpdf/backport-builder trong ngữ cảnh này.
Một ứng dụng phía sau chạy trên runtime PHP cũ hơn sẽ cài đặt gói nextpdf/backport được tạo ra từ kênh phát hành của gói đó. Ứng dụng này không bao giờ động đến repository này.

Trang này đề cập đến cả hai quy trình. Hãy đọc phần phù hợp với vai trò của bạn.

Cài đặt trên máy chủ build

Yêu cầu

Dependency	Ràng buộc	Nguồn xác thực
PHP	`>=8.4 <9.0`	`composer.jsonrequire.php`
Composer	2.6+	`CONTRIBUTING.md` bảng môi trường
`rector/rector`	`^2.0`	`composer.jsonrequire-dev`
`phpstan/phpstan`	`^2.1`	`composer.jsonrequire-dev`
`phpunit/phpunit`	`^13.0`	`composer.jsonrequire-dev`

Workflow CI cấp phát PHP 8.5 cho cả job build lẫn job chạy thử. Bất kỳ máy chủ build nào chạy phiên bản PHP trong khoảng >=8.4 <9.0 đều thỏa mãn ràng buộc của Composer. Trình phân tích cú pháp PHP phải chấp nhận được cú pháp mới nhất mà mã nguồn sử dụng. Nội dung này đã được kiểm chứng dựa trên .github/workflows/0-ci.yml.

Các bước

Clone repository, rồi check out nhánh tương ứng với target mà bạn muốn build. PHP74 là nhánh mặc định và tạo ra bản phân phối PHP 7.4 chỉ-có-core. PHP81 tạo ra bản phân phối PHP 8.1 kèm tất cả adapter.
Terminal window
```
git clone https://github.com/nextpdf-labs/backport.git
cd backport
git checkout PHP74
```
Cài đặt các dependency build. Không truyền --no-dev: engine Rector, PHPStan và PHPUnit nằm trong require-dev, và quá trình build không thể chạy khi thiếu chúng.
Terminal window
```
composer install --prefer-dist --no-progress
```
Xác nhận toolchain phân giải được. Script analyse chạy PHPStan ở cấp 10 trên rector/rules và scripts. Một lần chạy sạch cho thấy bản thân mã build đã vững chắc trước khi bạn tạo ra kết quả đầu ra.
Terminal window
```
composer analyse
```
Chạy các bài kiểm thử fixture cho rule. Mỗi rule Rector tùy chỉnh đều có một bộ fixture để xác nhận chính xác phép biến đổi before/after.
Terminal window
```
composer test
```

Sau bước 4, máy chủ đã sẵn sàng để build. Hãy đến /integrations/backport/quickstart/ để xem các lệnh chạy thử và build đầy đủ.

Cấu trúc cây nguồn được mong đợi

Quá trình build gộp nhiều repository nguồn thành một cây duy nhất. Hãy đặt chúng làm các thư mục ngang hàng dưới một thư mục gốc nguồn duy nhất; script gộp tham chiếu từng thư mục theo tên. Với target PHP 8.1, script đọc nextpdf (core), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, và nextpdf-Pro khi có bao gồm Pro. Với target PHP 7.4, script chỉ đọc nextpdf. Nội dung này đã được kiểm chứng dựa trên scripts/merge-sources.php (MergeSources::__construct()). Cung cấp thư mục gốc nguồn bằng --source-dir. Xem /integrations/backport/configuration/ để biết tài liệu tham khảo về các flag.

Sử dụng gói đã tạo ở phía sau

Khi hỗ trợ một dự án chạy trên runtime PHP cũ hơn, hãy cài đặt bản phân phối đã được tạo ra, chứ không phải builder này.

PHP 8.1 đến 8.3

composer require nextpdf/backport

Gói đã cài đặt khai báo ràng buộc >=8.1 <8.5 và thay thế nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter, và nextpdf/compat-legacy. Mã ứng dụng vẫn tiếp tục import namespace NextPDF\ mà không cần thay đổi. Gói tự động nạp cây đã gộp thông qua một prefix PHP Standard Recommendation 4 (PSR-4) duy nhất là NextPDF\, ánh xạ tới src/. Autoloader PSR-4 nối tên class tương đối vào thư mục cơ sở đã đăng ký cho prefix đó (PHP-FIG PSR-4). Nội dung này đã được kiểm chứng dựa trên scripts/adjust-composer.php (buildPublicAutoloadMap(), buildReplace()).

PHP 7.4 đến 8.0

composer require nextpdf/backport

Bản phân phối PHP 7.4 chỉ có core. Bản phân phối này khai báo ràng buộc >=7.4 <8.1 và chỉ thay thế nextpdf/core. Các adapter framework, lớp tương thích tcpdf và Pro không được bao gồm trong bản phân phối PHP 7.4. Nội dung này đã được kiểm chứng dựa trên scripts/adjust-composer.php và scripts/build.php (target PHP 7.4 bắt buộc chỉ-có-core). Dự án cần adapter framework thì cần PHP 8.1 trở lên.

Pro

composer require nextpdf/backport-pro

Bản phân phối Pro là một gói riêng biệt, nextpdf/backport-pro, với giấy phép proprietary. Bản phân phối này yêu cầu nextpdf/backport ở mức major.minor tương ứng và bổ sung phpseclib/phpseclib ^3.0. Nó chỉ được tạo ra cho target PHP 8.1. Nội dung này đã được kiểm chứng dựa trên scripts/adjust-composer.php (generateProComposer()).

Bản phân phối PHP 7.4 và bản phân phối Pro loại trừ lẫn nhau: do cách xây dựng của script build, không có bản build Pro cho PHP 7.4.

Polyfill trong gói đã tạo

Tệp composer.json được tạo ra yêu cầu các gói symfony/polyfill-* để các hàm thư viện chuẩn mới hơn có thể phân giải trên runtime target. Target PHP 8.1 yêu cầu các polyfill cho PHP 8.2 đến 8.5. Target PHP 7.4 cũng yêu cầu các polyfill cho PHP 8.0 và 8.1. Đây là các dependency runtime của gói được tạo ra, không phải của builder. Nội dung này đã được kiểm chứng dựa trên scripts/adjust-composer.php (generatePublicComposer()).

/integrations/backport/configuration/ — Cấu hình Rector, các rule tùy chỉnh và tài liệu tham khảo về các flag build.
/integrations/backport/quickstart/ — Lần chạy thử và build đầy đủ đầu tiên của bạn.