Bắt đầu nhanh với NextPDF Backport Builder

Đây là công cụ build — không phải phần phụ thuộc lúc chạy. Hãy chạy hướng dẫn này trên máy của người bảo trì hoặc máy continuous-integration (CI). Một dự án hạ nguồn sẽ sử dụng tệp lưu trữ mà bạn tạo ra. Các bước này không bao giờ chạy trên máy chủ ứng dụng.

Tổng quan nhanh

Bạn sẽ chạy ba lệnh. Trước tiên, chạy dry-run để xác nhận pipeline đã được kết nối mà không thay đổi tệp nào. Tiếp theo, chạy bản build PHP 8.1 đầy đủ. Sau đó, chạy bản build PHP 7.4 đầy đủ. Mỗi bước dùng một lệnh, dựa trên script Composer hoặc lệnh gọi scripts/build.php đã được ghi tài liệu.

Điều kiện cần

• Một máy build chạy PHP >=8.4 <9.0, đã cài các phần phụ thuộc dùng để build (composer install, không dùng --no-dev). Xem /integrations/backport/install/.
• Các repository mã nguồn được checkout thành các thư mục ngang hàng trong cùng một thư mục gốc nguồn. Bản build PHP 8.1 đọc nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, và nextpdf-Pro (cho Pro). Bản build PHP 7.4 chỉ đọc nextpdf. Đã đối chiếu với scripts/merge-sources.php.

Bước 1 — dry-run

Dry-run chạy mọi giai đoạn ở chế độ chỉ báo cáo. Giai đoạn merge liệt kê các tệp mà nó sẽ sao chép. Lệnh thông báo về Rector nhưng không chạy Rector. Các giai đoạn tạo composer, sao chép tài nguyên và kiểm tra hợp lệ in ra những việc chúng dự định làm. Không có gì được ghi. Hãy chạy bước này trước, vì đây là cách nhanh nhất để xác nhận bố cục mã nguồn và các cờ của bạn.

composer build:dry

composer build:dry ánh xạ tới php scripts/build.php --dry-run. Đã đối chiếu với composer.jsonscripts và scripts/build.php (nhánh dryRun trong mỗi giai đoạn). Với các cờ mặc định, target là php81, còn thư mục gốc nguồn dùng giá trị mặc định của script. Bạn có thể ghi đè bất kỳ giá trị nào trong hai giá trị này, như trình bày ở bước 2.

Nếu dry-run báo thiếu một repository mã nguồn, nó sẽ dừng ngay lập tức và nêu tên repository đó. Hãy sửa bố cục mã nguồn trước khi tiếp tục. Xem /integrations/backport/troubleshooting/.

Bước 2 — bản build PHP 8.1 đầy đủ

Bản build PHP 8.1 chạy tuần tự một số bước. Nó merge core với các adapter của framework và lớp tương thích tcpdf. Nó chạy cấu hình Rector một lượt. Nó tạo nextpdf/backportcomposer.json. Nó sao chép giấy phép, ghi CHANGELOG.md, và đếm số tệp PHP được tạo ra.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

Đã đối chiếu với điểm vào command-line interface (CLI) của scripts/build.php. Năm giai đoạn chạy lần lượt: merge nguồn, chạy downgrade bằng Rector, tạo composer.json, sao chép tài nguyên tĩnh, kiểm tra hợp lệ kết quả đầu ra. Mỗi giai đoạn in ra một dấu kiểm khi thành công. Giai đoạn đầu tiên thất bại sẽ dừng bản build và in lỗi của giai đoạn đó. Để loại bỏ Pro, hãy thêm --no-pro.

Khi thành công, orchestrator in ra thời gian đã trôi qua và đường dẫn đầu ra. Khi có bao gồm Pro, nó cũng in ra đường dẫn đầu ra của Pro. Khi đó, thư mục đầu ra chứa src/, tests/, một composer.json được tạo ra để khai báo bản đồ replace cùng các yêu cầu polyfill, LICENSE, và CHANGELOG.md.

Bước 3 — bản build PHP 7.4 đầy đủ

Bản build PHP 7.4 chỉ bao gồm core và dùng pipeline hai lượt. Nó chạy bước tiền xử lý enum, xóa cache, áp dụng các bản sửa sau Rector, rồi thực hiện downgrade đầy đủ.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

Đã đối chiếu với scripts/build.php. Ở đây, --target=php74 buộc chỉ dùng core, vô hiệu hóa Pro, và khiến runRector() chọn đường hai lượt. composer.json được tạo ra mang ràng buộc >=7.4 <8.1. Nó chỉ replace nextpdf/core và bổ sung các polyfill PHP 8.0 và 8.1 bên cạnh các polyfill 8.2–8.5.

Bước 4 — đọc kết quả đầu ra

Giai đoạn kiểm tra hợp lệ đếm các tệp PHP trong output/src và thất bại nếu số lượng bằng 0. Nó không chạy kiểm tra cú pháp trên máy cục bộ. Trình thông dịch cục bộ là PHP hiện đại của máy build, không phải runtime mục tiêu. Thay vào đó, nó in ra lệnh Docker để kiểm tra hợp lệ trên runtime mục tiêu thực tế. Đã đối chiếu với scripts/build.php (validateOutput()).

Để kiểm tra hợp lệ đầy đủ, hãy chạy kiểm tra cú pháp trên PHP mục tiêu. Quy trình phát hành đi theo cùng luồng này. Nó kiểm tra cú pháp kết quả đầu ra trên PHP 8.1 (hoặc PHP 7.4), rồi cài đặt và chạy thử trên toàn bộ ma trận hỗ trợ. Xem /integrations/backport/production-usage/.

Những gì bạn đã build

Artifact	Được build bởi	Ràng buộc	Thay thế cho
nextpdf/backport (PHP 8.1)	Bước 2	>=8.1 <8.5	core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro (PHP 8.1)	Bước 2, khi có bao gồm Pro	>=8.1 <8.5	nextpdf/pro
nextpdf/backport (PHP 7.4)	Bước 3	>=7.4 <8.1	nextpdf/core

Đã đối chiếu với scripts/adjust-composer.php.

Tiếp theo

• /integrations/backport/production-usage/ — Kết nối quy trình này vào quy trình phát hành dựa trên sự kiện.
• /integrations/backport/configuration/ — tài liệu tham khảo về các quy tắc và cờ đằng sau những lệnh này.
• /integrations/backport/troubleshooting/ — mọi lỗi của từng giai đoạn và ý nghĩa của nó.