การบูตและการค้นพบสำหรับ backport ของ NextPDF

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

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

ตัวสร้างไม่ใช้เฟรมเวิร์ก dependency-injection container หรือการค้นพบ service-provider แบบอัตโนมัติ แต่สคริปต์ PHP command-line interface (CLI) จะเชื่อมโยงกันด้วย require_once และ autoloader PSR-4 ของ Composer แทน ในที่นี้ “discovery” มีความหมายเฉพาะสองอย่าง คือขั้น merge อ่าน repository ต้นทางใด และ orchestrator เลือกการกำหนดค่า Rector สำหรับเป้าหมายอย่างไร

ภาพรวมไปป์ไลน์การสร้าง

orchestrator คือ scripts/build.php ซึ่งจะเริ่มการสร้างแล้วรันห้าขั้นตอนตามลำดับ แต่ละขั้นตอนมีการตรวจสอบเป็นด่าน ดังนั้นความล้มเหลวครั้งแรกจะหยุดการสร้าง:

1. Merge sources — คัดลอก repository ต้นทางทั้งหมดไปยังทรีเดียว
2. Run Rector downgrade — รันหนึ่งรอบสำหรับ PHP 8.1 รันสองรอบพร้อมการแก้ไขเพิ่มเติมสำหรับ PHP 7.4
3. Generate composer.json — เขียน manifest ของแพ็กเกจที่สร้างขึ้นพร้อมแมป replace ของแพ็กเกจนั้น
4. Copy static assets — คัดลอกไลเซนส์และ changelog ที่สร้างขึ้น
5. Validate output — นับไฟล์ PHP ที่ปล่อยออกมา ส่วนด่านตรวจไวยากรณ์ที่ชี้ขาดจะรันในภายหลังใน CI

ตรวจสอบแล้วกับ scripts/build.php (run(), step()) ดู /integrations/backport/configuration/ สำหรับรายละเอียดการเลือกกฎ และ /integrations/backport/production-usage/ สำหรับด่านตรวจ CI

การค้นพบโมดูลต้นทาง

การค้นพบต้นทางไม่ได้ขับเคลื่อนด้วย manifest แต่ scripts/merge-sources.php ใช้แมปแบบตายตัวที่ใช้ชื่อ repository เป็นคีย์และเลือกตามเป้าหมาย

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

การ merge จะวาง core ไว้ที่ src/ และวางอะแดปเตอร์แต่ละตัวไว้ภายใต้ไดเรกทอรีย่อยตามเนมสเปซของตน (src/Artisan/, src/Laravel/ เป็นต้น) Pro จะถูกวางไว้ในทรี pro/src/ ที่แยกต่างหาก เพื่อให้การสร้างปล่อยออกมาเป็นแพ็กเกจของตนเองได้ ตรวจสอบแล้วกับ MergeSources (mergeCore(), mergeArtisan(), mergePro())

ลำดับการบูต

1. scripts/build.php รันภายใต้ CLI Server Application Programming Interface (SAPI) โดยจะ require_once ทั้ง merge-sources.php และ adjust-composer.php
2. จุดเริ่มต้น CLI อ่านตัวเลือกด้วย getopt() — --version, --source-dir, --output-dir, --target, --dry-run, --no-pro เท่านั้น
3. มีการสร้างอินสแตนซ์ Build คอนสตรัคเตอร์จะตรวจสอบ --target เทียบกับ ['php74', 'php81'] และจะส่ง InvalidArgumentException สำหรับค่าที่ไม่ถูกต้องก่อนเริ่มงานใดๆ สำหรับเป้าหมาย PHP 7.4 คอนสตรัคเตอร์จะบังคับให้ผลลัพธ์เป็น core เท่านั้นและปิดใช้งาน Pro
4. Build::run() จะรันทั้งห้าขั้นตอนและออกด้วยสถานะ 0 เมื่อสำเร็จ หรือ 1 เมื่อเกิดความล้มเหลวครั้งแรก

ตรวจสอบแล้วกับ scripts/build.php (จุดเริ่มต้น CLI, Build::__construct(), run())

การ binding ของ container

ไม่เกี่ยวข้อง ตัวสร้างเป็นเครื่องมือ CLI ไม่มี dependency-injection container และไม่มี service container ของเฟรมเวิร์ก การเชื่อมโยงใช้การเรียก require_once อย่างชัดแจ้ง ร่วมกับการ autoload แบบ PSR-4 ของ Composer สำหรับ NextPDF\Backport\ (rules) และ NextPDF\Backport\Scripts\ (scripts) ตรวจสอบแล้วกับ composer.jsonautoload และคำสั่ง require_once ใน scripts/build.php

ลำดับการแก้ไขการกำหนดค่า

ไม่มีไฟล์การกำหนดค่า การกำหนดค่ามาจากแฟล็ก CLI ที่ปรับทับค่าเริ่มต้นซึ่งฝังอยู่ในสคริปต์:

1. แฟล็ก CLI หากมีการระบุ
2. ค่าเริ่มต้นในบล็อกการแยกวิเคราะห์ getopt() (เช่น target มีค่าเริ่มต้นเป็น php81 และ version มีค่าเริ่มต้นเป็น 2.0.0)
3. พฤติกรรมที่คอนสตรัคเตอร์อนุมานจากเป้าหมาย (PHP 7.4 บังคับให้เป็น core เท่านั้นและไม่มี Pro ไม่ว่าจะใช้ --no-pro หรือไม่ก็ตาม)

ตรวจสอบแล้วกับ scripts/build.php (จุดเริ่มต้น CLI และ Build::__construct()) ข้อมูลอ้างอิงแฟล็กฉบับเต็มอยู่ใน /integrations/backport/configuration/

การวินิจฉัย

orchestrator มีการวินิจฉัยของตนเอง รัน dry run (composer build:dry) เพื่อพิมพ์ repository ต้นทางที่จะถูกอ่านและเจตนาของแต่ละขั้นตอน โดยไม่เขียนสิ่งใด แต่ละขั้นตอนจะพิมพ์เครื่องหมายถูกเมื่อสำเร็จ หรือพิมพ์ความล้มเหลวพร้อมชื่อ ไม่มีคำสั่งย่อย diagnose ที่แยกต่างหากและไม่มีจุดเริ่มต้น bin/ ตัวสร้างจะรันผ่าน scripts/build.php หรือผ่านนามแฝงของ Composer-script ตรวจสอบแล้วกับ scripts/build.php (step(), สาขา dryRun), scripts/merge-sources.php (เส้นทาง dry-run ของ run()) และ composer.jsonscripts

ดูเพิ่มเติม

• /integrations/backport/overview/ — ตัวสร้างคืออะไรและสร้างผลลัพธ์ใด
• /integrations/backport/integration/ — สัญญาการผสานรวมของโฮสต์สำหรับการสร้าง
• /integrations/backport/configuration/ — การกำหนดค่า Rector และข้อมูลอ้างอิงแฟล็ก
• /integrations/backport/troubleshooting/ — ข้อมูลอ้างอิงความล้มเหลวทีละขั้นตอน