การแก้ปัญหา NextPDF Backport Builder

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

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

การบิลด์จะทำงานห้าขั้นตอนตามลำดับ และจะหยุดเมื่อพบความล้มเหลวแรกพร้อมพิมพ์ชื่อขั้นตอนและข้อความ ให้อ่านชื่อขั้นตอน แล้วค้นหาสาเหตุที่ตรงกันด้านล่าง ขั้นตอนต่างๆได้แก่ merge sources, run Rector downgrade, generate composer.json, copy static assets และ validate output ตรวจสอบยืนยันกับ scripts/build.php (run() และ step())

ขั้นตอน: merge sources

ข้อความแสดงข้อผิดพลาด “Source repo '' not found at: ”

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

วิธีแก้ไข: เช็กเอาต์ repository เป็นไดเรกทอรีระดับเดียวกันภายใต้พาธที่ส่งให้ --source-dir และใช้ชื่อไดเรกทอรีให้ตรงกับรายการด้านบนทุกประการ การรันแบบ dry run จะแสดงรายการ repository ทั้งหมดที่จะอ่าน ใช้การรันนี้เพื่อยืนยันโครงสร้างก่อนรันการบิลด์เต็มรูปแบบ

ขั้นตอน: run Rector downgrade

Rector ออกด้วยรหัสที่ไม่ใช่ศูนย์

ตัวควบคุมการทำงานจะรายงาน Rector failed on <label> (exit code: N) แล้วหยุด โดย label จะระบุรอบที่ล้มเหลว: public package, pro package, enum pre-processing หรือ full downgrade ตรวจสอบยืนยันกับ scripts/build.php (runRectorPass())

ตัวแก้ค่าพารามิเตอร์เริ่มต้นแครชเมื่อพบ enum เป็นค่าเริ่มต้น (PHP 7.4)

นี่คือเหตุผลที่เป้าหมาย PHP 7.4 ใช้สองรอบ ตัวแก้ค่าพารามิเตอร์เริ่มต้นของ Rector จะแครชเมื่อใช้ enum case เป็นค่าเริ่มต้นของ constructor promotion รอบที่ 1 (rector-php74-enums.php) จะแปลง enum เป็นคลาสรายการค่าคงที่ก่อน รอบเต็มในรอบที่ 2 จึงไม่พบค่าเริ่มต้นที่เป็น enum case อีก หากข้ามตัวควบคุมการทำงานและรันการกำหนดค่า PHP 7.4 แบบเต็มโดยตรงกับซอร์สที่มี enum ให้คาดว่าจะเกิดการแครชนี้ ตรวจสอบยืนยันกับ scripts/build.php (คอมเมนต์ runRector() และลำดับสองรอบ) และ rector/config/rector-php74-enums.php ด้วย

สคริปต์ benchmark ทำให้ Rector แครช

rector-php81.php และ rector-php74.php จะข้าม */tests/Benchmark/* สคริปต์เหล่านั้นอ้างถึงไลบรารี Portable Document Format (PDF) ภายนอกที่ Rector ไม่สามารถแก้การอ้างอิงได้ ทำให้ตัวแก้ค่าพารามิเตอร์เริ่มต้นแครช หากมีการประมวลผลพาธ benchmark แสดงว่า glob สำหรับการข้ามหายไปหรือพาธไม่ตรงกัน ตรวจสอบยืนยันกับ withSkip() ที่เรียกใช้

MHASH_XXH* ขัดข้อง (PHP 7.4)

rector-php74.php จะข้าม DowngradeHashAlgorithmXxHashRector กฎในตัวนี้จะแครชเมื่อพบค่าคงที่ของ xxHash ซอร์สไม่ได้ใช้ xxHash การข้ามจึงปลอดภัย ตรวจสอบยืนยันกับ rector/config/rector-php74.php (withSkip())

ขั้นตอน: post-Rector fix-ups (PHP 7.4 เท่านั้น)

การปรับแก้จะทำงานระหว่างสองรอบ และจะเขียนรูปแบบที่กฎ enum-to-class ทิ้งไว้ใหม่ หากเอาต์พุต PHP 7.4 มี parse error ที่เกี่ยวข้องกับ EnumClass::Case->value, ->name, เมท็อด enum เดิมที่ถูกเรียกเป็นเมท็อดของอินสแตนซ์ หรือ named argument บนชนิดที่แก้การอ้างอิงไม่ได้ แสดงว่าการปรับแก้ไม่ตรงกับรูปแบบนั้น ข้อจำกัดของ clone-with มีผลที่นี่เช่นกัน: การจับคู่อาร์กิวเมนต์ไม่ทำงานแบบเรียกซ้ำ ดังนั้นค่าแทนที่ที่มีวงเล็บซ้อนกันจะไม่ถูกเขียนใหม่ ตรวจสอบยืนยันกับ scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) และ rector/rules/DowngradeCloneWithRector.php (ข้อจำกัดที่มีการบันทึกไว้)

ขั้นตอน: generate composer.json

ขั้นตอนนี้จะย้ายไดเรกทอรี src/ และ tests/ ที่ประมวลผลแล้วจากไดเรกทอรี build-temp ไปยังไดเรกทอรีเอาต์พุต จากนั้นจะเขียน composer.json ที่สร้างขึ้น ความล้มเหลวที่นี่แทบทั้งหมดเป็นเงื่อนไขของระบบไฟล์: ไดเรกทอรีเอาต์พุตเขียนไม่ได้ หรือทรี build-temp หายไปเพราะ Rector ไม่ได้สร้างอะไรเลย ตรวจสอบยืนยันกับ scripts/build.php (adjustComposer(), moveTree())

ขั้นตอน: copy static assets

ขั้นตอนนี้จะคัดลอก LICENSE จาก source repository หลักและเขียน CHANGELOG.md ที่สร้างขึ้น หากไม่มี LICENSE การคัดลอกจะถูกข้ามไปอย่างเงียบๆและการบิลด์จะดำเนินต่อไป ส่วน changelog จะถูกเขียนเสมอ ความล้มเหลวที่นี่หมายความว่าไดเรกทอรีเอาต์พุตเขียนไม่ได้ระหว่างการบิลด์ ตรวจสอบยืนยันกับ scripts/build.php (copyStaticAssets())

ขั้นตอน: validate output

ข้อความแสดงข้อผิดพลาด “Output src/ directory not found” / “No PHP files found in output”

การตรวจสอบความถูกต้องต้องมี output/src ที่ไม่ว่างเปล่า ทรีที่ว่างเปล่าหมายความว่าขั้นตอน merge ไม่ได้คัดลอกอะไรเลย หรือการย้ายไฟล์ล้มเหลว ตรวจสอบยืนยันกับ scripts/build.php (validateOutput())

ข้อความ “Syntax validation: skipped (requires PHP runtime)”

นี่เป็นพฤติกรรมที่คาดไว้ ไม่ใช่ข้อผิดพลาด โฮสต์การบิลด์รัน PHP รุ่นใหม่ ไม่ใช่รันไทม์เป้าหมาย ขั้นตอนในเครื่องจึงเพียงนับไฟล์และพิมพ์คำสั่ง Docker สำหรับการตรวจไวยากรณ์จริง เกตตรวจไวยากรณ์ที่ใช้เป็นเกณฑ์อ้างอิงคือขั้นตอน php -l หลังการบิลด์ในเวิร์กโฟลว์การรีลีส ซึ่งรันภายใต้รันไทม์เป้าหมายจริง ตรวจสอบยืนยันกับ scripts/build.php (validateOutput()) และ .github/workflows/build.yml (ขั้นตอนตรวจไวยากรณ์ของ PHP 8.1 / PHP 7.4)

ข้อจำกัดที่ทราบ

ข้อจำกัดเหล่านี้เป็นสิ่งที่ติดมากับวิธีการ downgrade โดยธรรมชาติ และผ่านการตรวจสอบยืนยันกับกฎและส่วน “Known Limitations” ของ README.md ของโปรเจกต์:

• พรอเพอร์ตี readonly จะถูกนำออก การบิลด์จะลบ readonly ออก เพื่อให้การขยาย clone-with สามารถกำหนดค่าพรอเพอร์ตีได้อย่างชัดเจนบนรันไทม์รุ่นเก่า เอาต์พุตที่ผ่านการ downgrade จะไม่มีคุณสมบัติแบบเปลี่ยนแปลงไม่ได้ที่รันไทม์บังคับใช้อีกต่อไป
• #[Override] ไม่ถูกบังคับใช้บน PHP 8.1 แอตทริบิวต์นี้อาจยังคงอยู่ แต่รันไทม์รุ่นเก่าจะไม่ทำงานตามแอตทริบิวต์นี้
• เป้าหมาย PHP 7.4 เป็น core เท่านั้น อะแดปเตอร์เฟรมเวิร์ก เลเยอร์ tcpdf-compatibility และ Pro จะถูกตัดออกจากดิสทริบิวชัน PHP 7.4 ตามโครงสร้างของสคริปต์การบิลด์
• Pro เป็นแพ็กเกจแยกต่างหากและสำหรับ PHP 8.1 เท่านั้น ไม่มีการบิลด์ Pro สำหรับ PHP 7.4
• การจับคู่อาร์กิวเมนต์ของ clone-with ไม่ทำงานแบบเรียกซ้ำ ค่าแทนที่ที่มีวงเล็บซ้อนกันจะไม่ถูกแปลง และมีเพียงคีย์อาร์เรย์ที่เป็นสตริงเท่านั้นที่แก้การอ้างอิงเป็นชื่อพรอเพอร์ตีได้

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

• /integrations/backport/configuration/ — เอกสารอ้างอิงกฎและแฟล็ก
• /integrations/backport/production-usage/ — เกต CI และเลนการรีลีส