ติดตั้ง NextPDF Backport Builder

ติดตั้งเครื่องมือ build นี้บนเวิร์กสเตชันของผู้ดูแลหรือบน continuous integration (CI) runner เครื่องมือนี้ไม่ใช่ dependency ขณะรันไทม์ แอปพลิเคชันปลายทางจะไม่ติดตั้งตัวสร้าง แต่จะติดตั้งแพ็กเกจที่ตัวสร้างผลิตขึ้นแทน

ภาพรวมโดยย่อ

ผู้ใช้สองกลุ่มจะติดตั้งองค์ประกอบที่แตกต่างกัน:

ในฐานะ ผู้ดูแลหรือผู้ปฏิบัติงาน CI ให้โคลน repository นี้และติดตั้ง build dependencies ของ repository ติดตั้ง nextpdf/backport-builder เฉพาะในบริบทนี้เท่านั้น
ในฐานะ แอปพลิเคชันปลายทาง ที่ทำงานบน PHP รันไทม์รุ่นเก่ากว่า ให้ติดตั้งแพ็กเกจ nextpdf/backport ที่สร้างจากช่องทางรีลีสของแพ็กเกจ แอปพลิเคชันปลายทางจะไม่ต้องแตะต้อง repository นี้เลย

หน้านี้ครอบคลุมเวิร์กโฟลว์ทั้งสองแบบ โปรดอ่านส่วนที่ตรงกับบทบาทของท่าน

การติดตั้งบน build host

ข้อกำหนด

การพึ่งพา (Dependency)	ข้อจำกัด	แหล่งอ้างอิงที่ถูกต้อง
PHP	`>=8.4 <9.0`	`composer.jsonrequire.php`
Composer	2.6+	`CONTRIBUTING.md` ตารางสภาพแวดล้อม
`rector/rector`	`^2.0`	`composer.jsonrequire-dev`
`phpstan/phpstan`	`^2.1`	`composer.jsonrequire-dev`
`phpunit/phpunit`	`^13.0`	`composer.jsonrequire-dev`

เวิร์กโฟลว์ CI จัดเตรียม PHP 8.5 ให้ทั้งงาน build และงาน dry-run build host ใดก็ตามที่ใช้ PHP รุ่นในช่วง >=8.4 <9.0 จะตรงตามข้อจำกัดของ Composer ตัวแยกวิเคราะห์ของ PHP ต้องรองรับไวยากรณ์ล่าสุดที่ซอร์สใช้ อ้างอิงตาม .github/workflows/0-ci.yml ที่ตรวจสอบแล้ว

ขั้นตอน

โคลน repository จากนั้น check out branch สำหรับเป้าหมายที่ต้องการ build PHP74 คือ branch เริ่มต้น และผลิตดิสทริบิวชัน PHP 7.4 แบบ core เท่านั้น ส่วน PHP81 ผลิตดิสทริบิวชัน PHP 8.1 พร้อมอะแดปเตอร์ทั้งหมด
Terminal window
```
git clone https://github.com/nextpdf-labs/backport.git
cd backport
git checkout PHP74
```
ติดตั้ง build dependencies อย่าระบุ --no-dev เนื่องจากเอนจิน Rector, PHPStan และ PHPUnit อยู่ใน require-dev และการ build จะทำงานไม่ได้หากขาดองค์ประกอบเหล่านี้
Terminal window
```
composer install --prefer-dist --no-progress
```
ยืนยันว่า toolchain แก้ไขการพึ่งพาได้สำเร็จ สคริปต์ analyse จะรัน PHPStan ที่ระดับ 10 บน rector/rules และ scripts การรันที่ไม่มีข้อผิดพลาดแสดงว่าโค้ดของการ build เองถูกต้องก่อนสร้างเอาต์พุต
Terminal window
```
composer analyse
```
รันการทดสอบ fixture ของกฎ กฎ Rector ที่กำหนดเองแต่ละกฎมีชุด fixture สำหรับตรวจสอบการแปลง before/after อย่างแม่นยำ
Terminal window
```
composer test
```

หลังจากขั้นตอนที่ 4 host จะพร้อมสำหรับการ build ไปที่ /integrations/backport/quickstart/ สำหรับการเรียกใช้แบบ dry-run และแบบ full-build

โครงสร้างซอร์สทรีที่คาดหวัง

การ build จะรวม source repository หลายตัวเข้าด้วยกันเป็นทรีเดียว วางไดเรกทอรีเหล่านี้เป็นไดเรกทอรีระดับเดียวกันภายใต้ source root เดียว สคริปต์การรวมจะอ้างถึงแต่ละไดเรกทอรีตามชื่อ สำหรับเป้าหมาย PHP 8.1 สคริปต์จะอ่าน nextpdf (core), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter และ nextpdf-Pro เมื่อรวม Pro ไว้ด้วย สำหรับเป้าหมาย PHP 7.4 สคริปต์จะอ่านเฉพาะ nextpdf เท่านั้น ตรวจสอบแล้วกับ scripts/merge-sources.php (MergeSources::__construct()) ระบุ source root ด้วย --source-dir ดู /integrations/backport/configuration/ สำหรับการอ้างอิงแฟล็ก

การใช้งานแพ็กเกจที่ผลิตขึ้นจากฝั่งปลายทาง

เมื่อดูแลโปรเจกต์บน PHP รันไทม์รุ่นเก่ากว่า ให้ติดตั้งดิสทริบิวชันที่ผลิตขึ้น ไม่ใช่ตัวสร้างนี้

PHP 8.1 ถึง 8.3

composer require nextpdf/backport

แพ็กเกจที่ติดตั้งจะประกาศข้อจำกัด >=8.1 <8.5 และแทนที่ nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter และ nextpdf/compat-legacy โค้ดของแอปพลิเคชันยังคง import เนมสเปซ NextPDF\ ได้เหมือนเดิมโดยไม่ต้องเปลี่ยนแปลง แพ็กเกจจะ autoload ทรีที่รวมแล้วผ่านพรีฟิกซ์ PHP Standard Recommendation 4 (PSR-4) เพียงตัวเดียวคือ NextPDF\ ซึ่งแม็ปไปยัง src/ ตัว autoload แบบ PSR-4 จะต่อชื่อคลาสแบบสัมพัทธ์เข้ากับ base directory ที่ลงทะเบียนไว้สำหรับพรีฟิกซ์ (PHP-FIG PSR-4) ตรวจสอบแล้วกับ scripts/adjust-composer.php (buildPublicAutoloadMap(), buildReplace())

PHP 7.4 ถึง 8.0

composer require nextpdf/backport

ดิสทริบิวชัน PHP 7.4 เป็นแบบ core เท่านั้น ดิสทริบิวชันนี้จะประกาศข้อจำกัด >=7.4 <8.1 และแทนที่เฉพาะ nextpdf/core เท่านั้น อะแดปเตอร์เฟรมเวิร์ก เลเยอร์ความเข้ากันได้กับ tcpdf และ Pro ไม่ได้รวมอยู่ในดิสทริบิวชัน PHP 7.4 ตรวจสอบแล้วกับ scripts/adjust-composer.php และ scripts/build.php (เป้าหมาย PHP 7.4 บังคับให้เป็น core เท่านั้น) โปรเจกต์ที่ต้องใช้อะแดปเตอร์เฟรมเวิร์กต้องใช้ PHP 8.1 หรือใหม่กว่า

รุ่น Pro

composer require nextpdf/backport-pro

ดิสทริบิวชัน Pro เป็นแพ็กเกจแยกต่างหากชื่อ nextpdf/backport-pro ภายใต้ไลเซนส์ proprietary ดิสทริบิวชันนี้ต้องการ nextpdf/backport ที่มี major.minor ตรงกัน และเพิ่ม phpseclib/phpseclib ^3.0 ดิสทริบิวชันนี้ผลิตขึ้นสำหรับเป้าหมาย PHP 8.1 เท่านั้น ตรวจสอบแล้วกับ scripts/adjust-composer.php (generateProComposer())

ดิสทริบิวชัน PHP 7.4 และดิสทริบิวชัน Pro แยกขาดจากกันโดยสิ้นเชิง: ตามการออกแบบของสคริปต์การ build จะไม่มี build แบบ PHP 7.4 Pro

Polyfill ในแพ็กเกจที่ผลิตขึ้น

ไฟล์ composer.json ที่สร้างขึ้นจะต้องการแพ็กเกจ symfony/polyfill-* เพื่อให้ฟังก์ชันไลบรารีมาตรฐานรุ่นใหม่กว่าสามารถแก้ไขการพึ่งพาบนรันไทม์เป้าหมายได้ เป้าหมาย PHP 8.1 ต้องการ polyfill สำหรับ PHP 8.2 ถึง 8.5 เป้าหมาย PHP 7.4 ยังต้องการ polyfill สำหรับ PHP 8.0 และ 8.1 ด้วย รายการเหล่านี้เป็น dependency ขณะรันไทม์ของแพ็กเกจ ที่ผลิตขึ้น ไม่ใช่ของตัวสร้าง ตรวจสอบแล้วกับ scripts/adjust-composer.php (generatePublicComposer())

ขั้นตอนถัดไป

/integrations/backport/configuration/ — การตั้งค่า Rector กฎที่กำหนดเอง และการอ้างอิงแฟล็กของการ build
/integrations/backport/quickstart/ — การ dry-run และ full build ครั้งแรกของท่าน