ภาพรวม NextPDF Backport Builder

เครื่องมือนี้มีไว้สำหรับการบิลด์ ไม่ใช่ dependency แบบรันไทม์ ผู้ดูแล NextPDF ใช้แพ็กเกจนี้เพื่อสร้างชุดแจกจ่ายของ NextPDF ที่เข้ากันได้กับ PHP 8.1+ และ PHP 7.4+ แอปพลิเคชันต้องไม่เพิ่มแพ็กเกจนี้เป็น dependency แบบรันไทม์โดยเด็ดขาด

ภาพรวมโดยสรุป

NextPDF Backport Builder คือโครงสร้างพื้นฐานสำหรับการบิลด์ที่ใช้สร้างชุดแจกจ่ายแบบลดระดับของระบบนิเวศ NextPDF สำหรับรันไทม์ PHP ที่เก่ากว่าเส้นฐานการพัฒนา NextPDF เขียนขึ้นสำหรับ PHP รุ่นใหม่และใช้ไวยากรณ์ที่อินเทอร์พรีเตอร์รุ่นก่อนหน้าไม่ยอมรับ บิลเดอร์ส่งซอร์สผ่าน Rector ซึ่งเป็นเอนจินสำหรับแปลง abstract syntax tree แล้วปล่อยแพ็กเกจที่มีไวยากรณ์ซึ่งรันไทม์ PHP 8.1 หรือ PHP 7.4 ยอมรับ

ชื่อแพ็กเกจ Composer คือ nextpdf/backport-builder แพ็กเกจนี้ประกาศ "type": "project" และไม่มี dependency แบบรันไทม์ของ NextPDF ข้อกำหนดของแพ็กเกจมีเฉพาะเอนจินสำหรับการบิลด์ (rector/rector) การวิเคราะห์แบบสถิต (phpstan/phpstan) ตัวรันการทดสอบ (phpunit/phpunit) และชุดแพ็กเกจ symfony/polyfill-* ที่ใช้ในผลลัพธ์ที่สร้างขึ้น โดย composer.json ที่รากของรีโพยืนยันเรื่องนี้

สิ่งที่แพ็กเกจนี้ไม่ใช่

รีโพนี้ไม่ได้บรรจุเอนจิน NextPDF แต่บรรจุกฎและสคริปต์ที่แปลงเอนจินนั้นให้อยู่ในรูปแบบ backport การแยกส่วนนี้มีผลในทางปฏิบัติสามประการ:

• อย่าติดตั้งแพ็กเกจนี้เพื่อเรนเดอร์ PDF ให้ติดตั้ง nextpdf/backport ซึ่งเป็นอาร์ทิแฟกต์ที่บิลเดอร์นี้สร้างขึ้น และเก็บบิลเดอร์ไว้บนโฮสต์ของผู้ดูแลหรือโฮสต์ continuous integration (CI)
• อย่าพัฒนาบนโค้ดที่ถูกสร้างขึ้น ชุดแจกจ่ายที่สร้างขึ้นเป็นอาร์ทิแฟกต์แบบอ่านอย่างเดียวที่สร้างโดยเครื่อง ส่งรายงานข้อบกพร่องและคำขอฟีเจอร์ไปยังรีโพซอร์ส nextpdf/* ต้นฉบับ
• ผลลัพธ์ถูกส่งมอบในรูปแบบแท็กเวอร์ชัน ไม่ใช่ในรูปแบบสาขาของรีโพนี้ ไปป์ไลน์การปล่อยรุ่นจะติดแท็กทรีที่สร้างขึ้นและแนบไฟล์อาร์ไคฟ์เข้ากับการปล่อยรุ่นบน GitHub

สิ่งที่สร้างขึ้น

บิลเดอร์ปล่อยแพ็กเกจ Composer ที่มีชื่อและสัญญาอนุญาตตามที่ scripts/adjust-composer.php กำหนดไว้:

แพ็กเกจที่สร้างขึ้น	สัญญาอนุญาต	ขอบเขต	บิลด์เมื่อ
nextpdf/backport	Apache-2.0	Core, อะแดปเตอร์เฟรมเวิร์ก และเลเยอร์ความเข้ากันได้กับ tcpdf สำหรับเป้าหมาย PHP 8.1	เสมอ
nextpdf/backport-pro	proprietary	โมดูล Pro ที่ปล่อยเป็นแพ็กเกจแยกต่างหาก	เป้าหมาย PHP 8.1 เมื่อมีซอร์ส Pro และไม่ได้ยกเว้น Pro

แพ็กเกจ nextpdf/backport ประกาศรายการ replace ของ Composer เพื่อให้หลังการติดตั้ง แพ็กเกจนี้ตอบสนองข้อจำกัดของแพ็กเกจต้นฉบับได้ สำหรับเป้าหมาย PHP 8.1 แพ็กเกจที่ถูกแทนที่คือ nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter และ nextpdf/compat-legacy สำหรับเป้าหมาย PHP 7.4 จะมีเพียง nextpdf/core เท่านั้นที่ถูกแทนที่ เนื่องจากการบิลด์ PHP 7.4 เป็นแบบ core เท่านั้น scripts/adjust-composer.php (buildReplace()) ยืนยันเรื่องนี้

ออโต้โหลดเดอร์ของผู้ใช้ปลายทางจะ resolve ทรีที่ผสานแล้วผ่านพรีฟิกซ์ PHP Standards Recommendation 4 (PSR-4) หนึ่งรายการคือ NextPDF\ ซึ่งแมปไปยัง src/ ตาม PSR-4 พรีฟิกซ์ของเนมสเปซจะถูกแมปไปยังไดเรกทอรีฐาน และชื่อคลาสแบบ fully qualified แต่ละชื่อจะถูก resolve ไปยังไฟล์ภายใต้ไดเรกทอรีนั้น ดู PHP Framework Interop Group (PHP-FIG) PSR-4 แพ็กเกจ Pro แมป NextPDF\Pro\ ไปยัง src/ ของตนเอง

เมทริกซ์ PHP ที่รองรับ

เมทริกซ์ด้านล่างครอบคลุมเฉพาะสิ่งที่การกำหนดค่า Rector และสคริปต์สำหรับการบิลด์บังคับใช้เท่านั้น โฮสต์สำหรับการบิลด์จะรัน PHP เวอร์ชันใหม่เสมอ ส่วน ผลลัพธ์ จะมุ่งเป้าไปที่เวอร์ชันที่เก่ากว่า

ประเด็น	ค่า	หลักฐาน
PHP บนโฮสต์สำหรับการบิลด์	>=8.4 <9.0	composer.jsonrequire.php
PHP สำหรับ build/test ของ CI	8.5	.github/workflows/0-ci.yml, build.yml (shivammathur/setup-phpphp-version: '8.5')
ข้อจำกัดผลลัพธ์ของเป้าหมาย PHP 8.1	>=8.1 <8.5	scripts/adjust-composer.php (generatePublicComposer())
ข้อจำกัดผลลัพธ์ของเป้าหมาย PHP 7.4	>=7.4 <8.1	scripts/adjust-composer.php (generatePublicComposer())
ขอบเขตของเป้าหมาย PHP 8.1	Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro แยกต่างหาก)	scripts/merge-sources.php, scripts/adjust-composer.php
ขอบเขตของเป้าหมาย PHP 7.4	Core เท่านั้น	scripts/build.php (--target=php74 บังคับให้เป็น core เท่านั้น ปิดใช้งาน Pro)

การบิลด์ PHP 8.1 ได้รับการตรวจสอบความถูกต้องบน PHP 8.1, 8.2, 8.3 และ 8.4 ส่วนการบิลด์ PHP 7.4 ได้รับการตรวจสอบความถูกต้องบน PHP 7.4 และ 8.0 เมทริกซ์งาน validate-php81 และ validate-php74 ใน .github/workflows/build.yml ยืนยันเรื่องนี้ รายการเหล่านี้คือรันไทม์ที่ไปป์ไลน์ทดสอบใช้งานจริง และเป็นชุดการตรวจสอบความถูกต้องที่สังเกตได้ ไม่ใช่การอ้างความสอดคล้องตามมาตรฐาน

โมเดลสองสาขา

รีโพนี้ไม่มีสาขา main โดย PHP74 เป็นสาขาเริ่มต้น และ PHP81 เป็นสาขาถาวรสาขาที่สอง สาขาที่ใช้จะกำหนดสองสิ่ง ได้แก่ เป้าหมายเริ่มต้นของการบิลด์ในเครื่องและชุดซอร์สที่ถูกผสาน หากการเปลี่ยนแปลงส่งผลต่อทั้งสองเป้าหมาย ให้นำการเปลี่ยนแปลงนั้นไปใช้กับแต่ละสาขาผ่าน pull request ของสาขานั้นเอง เวิร์กโฟลว์ CI รันบนทั้ง PHP74 และ PHP81 ซึ่งยืนยันได้จาก git branch -a และ .github/workflows/0-ci.yml (branches: [PHP74, PHP81])

การปล่อยรุ่นเกิดขึ้นอย่างไร

เส้นทางการปล่อยรุ่นขับเคลื่อนด้วยเหตุการณ์ เมื่อองค์กรซอร์สของ NextPDF เผยแพร่แท็กการปล่อยรุ่น เหตุการณ์ repository-dispatch ชนิด source-release จะทริกเกอร์เวิร์กโฟลว์การบิลด์ เวิร์กโฟลว์จะเช็กเอาต์รีโพซอร์สแต่ละรายการที่มีแท็กตรงกัน รันไปป์ไลน์ ตรวจสอบไวยากรณ์ของผลลัพธ์บนรันไทม์เป้าหมาย ตรวจสอบความถูกต้องทั่วทั้งเมทริกซ์ที่รองรับ และแนบไฟล์อาร์ไคฟ์เข้ากับการปล่อยรุ่นบน GitHub แท็กเวอร์ชันเป็นไปตาม Semantic Versioning: หมายเลขเวอร์ชันคือ MAJOR.MINOR.PATCH สำหรับ API สาธารณะที่ประกาศไว้ (Semantic Versioning 2.0.0 §2) .github/workflows/build.yml ยืนยันเรื่องนี้

ไปต่อที่ไหน

• /integrations/backport/install/ — วิธีติดตั้งบิลเดอร์บนโฮสต์สำหรับการบิลด์ และวิธีที่ผู้ใช้ปลายทางติดตั้งแพ็กเกจที่สร้างขึ้น
• /integrations/backport/configuration/ — การกำหนดค่า Rector กฎที่กำหนดเอง และแฟล็กสำหรับการบิลด์
• /integrations/backport/quickstart/ — การรันทดลองแบบอิงซอร์สและการเรียกใช้บิลด์เต็มรูปแบบ
• /integrations/backport/production-usage/ — วิธีเชื่อมต่อบิลเดอร์เข้ากับเวิร์กโฟลว์การปล่อยรุ่น
• /integrations/backport/troubleshooting/ — รูปแบบความล้มเหลวที่ไปป์ไลน์ป้องกันไว้และวิธีอ่านความล้มเหลวเหล่านั้น
• /integrations/backport/security-and-operations/ — สถานะความปลอดภัยของซัพพลายเชน ขอบเขตความเชื่อถือ และการรับประกันด้านการดำเนินงาน
• /integrations/backport/boot-and-discovery/ — วิธีที่บิลเดอร์ค้นพบโมดูลซอร์สและบูต
• /integrations/backport/integration/ — สัญญาการผสานรวมบนโฮสต์สำหรับการบิลด์