คู่มือเริ่มต้นใช้งาน NextPDF Backport Builder อย่างรวดเร็ว

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

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

คุณจะเรียกใช้คำสั่งสามคำสั่ง ขั้นแรกให้เรียกใช้ dry-run เพื่อยืนยันว่าไปป์ไลน์เชื่อมต่อกันถูกต้องโดยไม่แตะไฟล์ใด ต่อมาให้เรียกใช้การบิลด์ PHP 8.1 เต็มรูปแบบ แล้วจึงเรียกใช้การบิลด์ PHP 7.4 เต็มรูปแบบ แต่ละขั้นใช้เพียงคำสั่งเดียว โดยมีสคริปต์ Composer หรือการเรียกใช้ scripts/build.php รองรับตามที่ระบุไว้ในเอกสาร

ข้อกำหนดเบื้องต้น

โฮสต์สำหรับบิลด์ที่ใช้ PHP >=8.4 <9.0 พร้อมติดตั้งดีเพนเดนซีสำหรับบิลด์แล้ว (composer install โดยไม่ใช้ --no-dev) ดู /integrations/backport/install/
รีโพซิทอรีซอร์สที่เช็กเอาต์ไว้ในไดเรกทอรีระดับเดียวกันภายใต้ซอร์สรูทเดียวกัน การบิลด์ PHP 8.1 จะอ่าน nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter และ nextpdf-Pro (สำหรับ Pro) การบิลด์ PHP 7.4 จะอ่านเฉพาะ nextpdf เท่านั้น ตรวจสอบกับ scripts/merge-sources.php แล้ว

ขั้นที่ 1 — dry-run

dry-run จะเรียกใช้ทุกสเตจในโหมดรายงานเท่านั้น สเตจ merge จะแสดงรายการไฟล์ที่จะคัดลอก คำสั่งจะประกาศ Rector แต่ไม่เรียกใช้ สเตจสำหรับสร้าง composer คัดลอกแอสเซต และตรวจสอบความถูกต้องจะพิมพ์การดำเนินการที่ตั้งใจจะทำ โดยจะไม่เขียนข้อมูลใด ให้เรียกใช้ขั้นนี้ก่อน เพราะเป็นวิธีที่เร็วที่สุดในการยืนยันเลย์เอาต์ของซอร์สและแฟล็กของคุณ

composer build:dry

composer build:dry จะถูกแปลงเป็น php scripts/build.php --dry-run ตรวจสอบกับ composer.jsonscripts และ scripts/build.php แล้ว (สาขา dryRun ในแต่ละสเตจ) เมื่อใช้แฟล็กค่าเริ่มต้น เป้าหมายจะเป็น php81 และซอร์สรูทจะใช้ค่าเริ่มต้นของสคริปต์ คุณสามารถแทนที่ค่าใดค่าหนึ่งได้ตามที่แสดงในขั้นที่ 2

หาก dry-run รายงานว่าไม่พบรีโพซิทอรีซอร์ส กระบวนการจะหยุดทำงานทันทีและระบุชื่อรีโพซิทอรีนั้น แก้ไขเลย์เอาต์ของซอร์สก่อนดำเนินการต่อ ดู /integrations/backport/troubleshooting/

ขั้นที่ 2 — การบิลด์ PHP 8.1 เต็มรูปแบบ

การบิลด์ PHP 8.1 จะเรียกใช้หลายขั้นตอนตามลำดับ รวม core เข้ากับอะแดปเตอร์ของเฟรมเวิร์กและเลเยอร์ความเข้ากันได้กับ tcpdf เรียกใช้การกำหนดค่า Rector แบบ single-pass สร้าง nextpdf/backportcomposer.json คัดลอกไลเซนส์ เขียน CHANGELOG.md และนับจำนวนไฟล์ PHP ที่สร้างออกมา

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

ตรวจสอบกับจุดเริ่มต้น (entry point) ของอินเทอร์เฟซบรรทัดคำสั่ง (CLI) scripts/build.php แล้ว สเตจทั้งห้าจะเรียกใช้ตามลำดับ ได้แก่ รวมซอร์ส เรียกใช้การดาวน์เกรดด้วย Rector สร้าง composer.json คัดลอกแอสเซตแบบสแตติก และตรวจสอบความถูกต้องของเอาต์พุต แต่ละสเตจจะพิมพ์เครื่องหมายถูกเมื่อสำเร็จ สเตจแรกที่ล้มเหลวจะหยุดการบิลด์และพิมพ์ข้อผิดพลาดของสเตจนั้น หากต้องการยกเว้น Pro ให้เพิ่มแฟล็ก --no-pro ในคำสั่ง

เมื่อสำเร็จ ตัวจัดการ (orchestrator) จะพิมพ์เวลาที่ใช้ไปและพาธของเอาต์พุต หากรวม Pro ด้วย จะพิมพ์พาธของเอาต์พุต Pro เพิ่มเติม จากนั้นไดเรกทอรีเอาต์พุตจะมี src/, tests/, ไฟล์ composer.json ที่สร้างขึ้นพร้อมแมป replace และข้อกำหนด polyfill, LICENSE และ CHANGELOG.md รวมอยู่ด้วย

ขั้นที่ 3 — การบิลด์ PHP 7.4 เต็มรูปแบบ

การบิลด์ PHP 7.4 เป็นแบบ core เท่านั้นและใช้ไปป์ไลน์แบบ two-pass โดยเรียกใช้การประมวลผลล่วงหน้าของ enum ล้างแคช ใช้การแก้ไขหลัง Rector แล้วจึงดำเนินการดาวน์เกรดเต็มรูปแบบ

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

ตรวจสอบกับ scripts/build.php แล้ว ในที่นี้ --target=php74 จะบังคับให้เป็นแบบ core เท่านั้น ปิดใช้งาน Pro และทำให้ runRector() เลือกเส้นทางแบบ two-pass ไฟล์ composer.json ที่สร้างขึ้นจะมีข้อจำกัด >=7.4 <8.1 โดยแทนที่เฉพาะ nextpdf/core และเพิ่ม polyfill ของ PHP 8.0 และ 8.1 เพิ่มเติมจาก polyfill ของ 8.2–8.5

ขั้นที่ 4 — อ่านเอาต์พุต

สเตจตรวจสอบความถูกต้องจะนับจำนวนไฟล์ PHP ใน output/src และจะล้มเหลวหากนับได้เป็นศูนย์ สเตจนี้จะไม่เรียกใช้การตรวจสอบไวยากรณ์ในเครื่อง เพราะอินเทอร์พรีเตอร์ในเครื่องคือ PHP เวอร์ชันใหม่ของโฮสต์สำหรับบิลด์ ไม่ใช่รันไทม์เป้าหมาย แต่จะพิมพ์คำสั่ง Docker สำหรับตรวจสอบความถูกต้องกับรันไทม์เป้าหมายจริงแทน ตรวจสอบกับ scripts/build.php แล้ว (validateOutput())

หากต้องการตรวจสอบความถูกต้องอย่างสมบูรณ์ ให้เรียกใช้การตรวจสอบไวยากรณ์บน PHP เป้าหมาย เวิร์กโฟลว์การรีลีสใช้เส้นทางเดียวกัน โดยตรวจสอบไวยากรณ์ของเอาต์พุตบน PHP 8.1 (หรือ PHP 7.4) จากนั้นติดตั้งและทดสอบการทำงานทั่วทั้งเมทริกซ์การรองรับ ดู /integrations/backport/production-usage/

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

อาร์ติแฟกต์	สร้างโดย	ข้อจำกัด	แทนที่
`nextpdf/backport` (PHP 8.1)	ขั้นที่ 2	`>=8.1 <8.5`	โมดูล core + artisan + laravel + symfony + codeigniter + compat-legacy
`nextpdf/backport-pro` (PHP 8.1)	ขั้นที่ 2 เมื่อรวม Pro ด้วย	`>=8.1 <8.5`	`nextpdf/pro`
`nextpdf/backport` (PHP 7.4)	ขั้นที่ 3	`>=7.4 <8.1`	`nextpdf/core`

ตรวจสอบกับ scripts/adjust-composer.php แล้ว

ขั้นตอนต่อไป

/integrations/backport/production-usage/ — เชื่อมต่อขั้นตอนนี้เข้ากับเวิร์กโฟลว์การรีลีสแบบ event-driven
/integrations/backport/configuration/ — ข้อมูลอ้างอิงสำหรับกฎและแฟล็กที่อยู่เบื้องหลังคำสั่งเหล่านี้
/integrations/backport/troubleshooting/ — ความล้มเหลวของแต่ละสเตจและความหมายของแต่ละกรณี