เอกสารอ้างอิง API ของ Backport Builder

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

Backport Builder เป็นเครื่องมือสำหรับการบิลด์ ไม่ใช่ไลบรารีสำหรับรันไทม์ อินเทอร์เฟซสาธารณะของ Backport Builder ประกอบด้วยชุดคำสั่งบิลด์ (scripts/build.php และตัวห่อหุ้ม composer build*) คลาสระดับสคริปต์สี่คลาสที่อยู่เบื้องหลัง (Build, MergeSources, AdjustComposer, ValidateBuildContract) ไฟล์กำหนดค่า Rector สามไฟล์ กฎ Rector แบบกำหนดเองสามกฎ และสัญญาของแพ็กเกจที่สร้างขึ้น (nextpdf/backport และ nextpdf/backport-pro) ให้รัน Backport Builder บนโฮสต์ที่ใช้บิลด์หรือ continuous integration (CI) เพื่อแปลงซอร์ส NextPDF สมัยใหม่ให้เป็นชุดแจกจ่ายที่ดาวน์เกรดแล้ว ห้ามเพิ่ม Backport Builder ลงในแอปพลิเคชันโดยเด็ดขาด

หากเพิ่งเริ่มใช้งาน ให้เริ่มจาก composer build:dry (ซึ่งแปลงเป็น php scripts/build.php --dry-run) คำสั่งนี้จะรันทุกขั้นตอนในโหมดรายงานอย่างเดียวโดยไม่เขียนไฟล์ จึงช่วยตรวจสอบเค้าโครงซอร์สและแฟล็กก่อนการบิลด์จริงได้ ตัวอย่างแรกใน “งานที่ใช้บ่อย” แสดงคำสั่งเดียวกัน

งานที่ใช้บ่อย

โดยทั่วไปจะใช้แพ็กเกจนี้เพื่อรันการบิลด์บนโฮสต์ที่ใช้บิลด์ ตัวอย่างแต่ละรายการด้านล่างเป็นคำสั่งเดียว ซึ่งตรวจสอบความถูกต้องกับ scripts/build.php และ composer.json แล้ว

ตรวจสอบไปป์ไลน์โดยไม่เขียนสิ่งใดเลย (ปลอดภัยสำหรับการรันครั้งแรก):

composer build:dry

คำสั่งนี้แปลงเป็น php scripts/build.php --dry-run และจะรันการผสานซอร์ส การรัน Rector การสร้าง composer การคัดลอกแอสเซ็ต และการตรวจสอบในโหมดรายงานอย่างเดียว โดยไม่คัดลอกสิ่งใด

สร้างชุดแจกจ่าย PHP 8.1 แบบเต็ม (nextpdf/backport รวมถึง nextpdf/backport-pro เมื่อมีซอร์ส Pro):

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

คำสั่งนี้จะผสานคอร์ อะแดปเตอร์ของเฟรมเวิร์ก และเลเยอร์ความเข้ากันได้ของ tcpdf แล้วรัน Rector หนึ่งรอบสำหรับเป้าหมาย PHP 8.1 และเขียนโครงสร้างแพ็กเกจที่สร้างขึ้นไปยัง ./output เพิ่ม --no-pro เพื่อข้ามแพ็กเกจ Pro

สร้างชุดแจกจ่าย PHP 7.4 แบบคอร์อย่างเดียว (ไปป์ไลน์ enum แบบสองรอบ):

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

--target=php74 จะบังคับให้เอาต์พุตเป็นคอร์อย่างเดียว ปิดใช้งาน Pro และรันการประมวลผลล่วงหน้าของ enum การแก้ไขหลัง Rector และรอบการดาวน์เกรด PHP 7.4 แบบเต็ม

พื้นผิวคำสั่ง

ใช้ตารางนี้เมื่อต้องการดูลายเซ็น แฟล็ก และพฤติกรรมการออกที่แน่นอนของจุดเริ่มต้นการบิลด์ รวมถึงคลาสระดับสคริปต์ที่ขับเคลื่อนการบิลด์

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	ค่าที่ส่งคืน	ข้อยกเว้นหรือเงื่อนไขล้มเหลว	หมายเหตุ
scripts/build.php	เป้าหมาย เวอร์ชัน พาธซอร์ส พาธเอาต์พุต และแฟล็กตามที่สคริปต์ระบุ	ใช้ค่าเริ่มต้นของเป้าหมายตามแบรนช์	โครงสร้างแพ็กเกจที่สร้างขึ้น	รหัสออกที่ไม่ใช่ศูนย์และเอาต์พุตข้อผิดพลาดเฉพาะขั้นตอน	จุดเริ่มต้นหลักของการบิลด์ ให้รันบนโฮสต์ที่ใช้บิลด์ ไม่ใช่ในแอปพลิเคชัน
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false)	เวอร์ชัน ไดเรกทอรีซอร์ส ไดเรกทอรีเอาต์พุต เลนรันไทม์เป้าหมาย แฟล็กรวม Pro และแฟล็ก dry-run	กำหนดเป้าหมายเป็น PHP 8.1 รวม Pro ยกเว้นกรณี PHP 7.4 และเขียนไฟล์เว้นแต่จะเปิดใช้งาน dry-run	Build	InvalidArgumentException สำหรับเป้าหมายที่ไม่รองรับ ข้อผิดพลาดของขั้นตอนระหว่างการทำงานของ run()	คลาสระดับสคริปต์ที่อยู่เบื้องหลัง scripts/build.php โดยตรง
Build::run()	ไม่มี	ตรวจสอบสัญญา ผสานซอร์ส ปรับข้อมูลเมตาของ composer.json และรัน Rector หลายรอบ	bool	ส่งคืน false สำหรับความล้มเหลวของขั้นตอนที่คาดไว้ และอาจโยนข้อยกเว้นสำหรับข้อผิดพลาดของระบบไฟล์หรือรันไทม์ที่ไม่คาดคิด	CI ควรถือว่าล้มเหลวเมื่อได้ false เสมอ
composer build:dry	ตัวห่อหุ้มสคริปต์ของ Composer	การตรวจสอบการบิลด์แบบ dry-run	สถานะการออกและบันทึก	รหัสออกที่ไม่ใช่ศูนย์เมื่อการบิลด์หรือการตรวจสอบล้มเหลว	ใช้เป็นเกตของ CI
scripts/merge-sources.php	พาธเช็กเอาต์ซอร์สและเป้าหมายการผสาน	ผสานแพ็กเกจซอร์สที่เลือกไว้สำหรับรันไทม์เป้าหมาย	โครงสร้างซอร์สที่ผสานแล้ว	ไม่พบซอร์ส เป้าหมายที่ไม่รองรับ ความล้มเหลวของระบบไฟล์	รักษาการอ้างอิงซอร์สให้ตรงกับแท็กของรุ่นที่เผยแพร่
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false)	ไดเรกทอรีฐานของซอร์ส ไดเรกทอรีเอาต์พุต แฟล็กรวม Pro แฟล็ก dry-run และแฟล็กคอร์อย่างเดียว	ผสานที่เก็บโค้ดทั้งหมดที่กำหนดค่าไว้ หรือเฉพาะคอร์เมื่อ coreOnly เป็น true	MergeSources	พาธซอร์สหรือเอาต์พุตไม่ถูกต้องระหว่างการรัน	คลาสระดับสคริปต์ที่อยู่เบื้องหลัง scripts/merge-sources.php โดยตรง
MergeSources::run()	ไม่มี	คัดลอกและปรับโครงสร้างซอร์สที่เลือกไว้ให้เป็นมาตรฐานไปยังเป้าหมายการบิลด์	bool	ส่งคืน false สำหรับความล้มเหลวของการผสานที่คาดไว้	สามารถอ่านบันทึกได้ด้วย getLog() เสมอ
MergeSources::getLog()	ไม่มี	ส่งคืนรายการบันทึกของขั้นตอนที่สะสมไว้	array	ไม่คาดว่าจะมี	ใช้สำหรับการวินิจฉัยใน CI
scripts/adjust-composer.php	ข้อมูลเมตาและเวอร์ชันของ composer.json ที่สร้างขึ้น	เขียนข้อจำกัดของแพ็กเกจและรายการ replace สำหรับเอาต์พุตที่สร้างขึ้น	composer.json ที่ปรับแล้ว	เวอร์ชันไม่ถูกต้องหรือไม่พบไฟล์ที่สร้างขึ้น	กำหนดเอกลักษณ์ของแพ็กเกจที่สร้างขึ้น
AdjustComposer::__construct(string $version, string $target = 'php81')	สตริงเวอร์ชันและเลนเป้าหมาย	เป้าหมาย PHP 8.1	AdjustComposer	ข้อผิดพลาดจากเป้าหมายที่ไม่ถูกต้องในพาธการสร้าง	ใช้โดยสคริปต์การบิลด์และการทดสอบ
AdjustComposer::generatePublicComposer()	ไม่มี	สร้างข้อมูลเมตาสำหรับ nextpdf/backport	array	ไม่คาดว่าจะมี	API สร้างข้อมูลแบบไม่มีผลข้างเคียงสำหรับการทดสอบ
AdjustComposer::generateProComposer()	ไม่มี	สร้างข้อมูลเมตาสำหรับ nextpdf/backport-pro	array	ไม่คาดว่าจะมี	API สร้างข้อมูลแบบไม่มีผลข้างเคียงสำหรับเลนการบิลด์แบบกรรมสิทธิ์
AdjustComposer::writePublicComposer(string $outputDir)	ไดเรกทอรีเอาต์พุต	เขียน composer.json สาธารณะที่สร้างขึ้น	void	ข้อผิดพลาดของระบบไฟล์	ใช้เฉพาะในไดเรกทอรีเอาต์พุตที่สร้างขึ้นเท่านั้น
AdjustComposer::writeProComposer(string $proOutputDir)	ไดเรกทอรีเอาต์พุต Pro	เขียน composer.json ของ Pro ที่สร้างขึ้น	void	ข้อผิดพลาดของระบบไฟล์	ต้องมีโครงสร้างเอาต์พุต Pro อยู่แล้ว
ValidateBuildContract::__construct(string $repoRoot)	รากของที่เก็บโค้ด	ใช้รากของที่เก็บโค้ดที่ระบุเป็นฐานของสัญญา	ValidateBuildContract	ไม่คาดว่าจะมี	ตัวตรวจสอบสัญญาระดับสคริปต์
ValidateBuildContract::run()	ไม่มี	ตรวจสอบอินพุตที่จำเป็นและข้อสมมติของการบิลด์	bool	ส่งคืน false เมื่อสัญญาล้มเหลว	รันก่อนเชื่อถือเอาต์พุตของการบิลด์

การกำหนดค่า Rector

ใช้ตารางนี้เพื่อดูว่าไฟล์กำหนดค่า Rector ใดขับเคลื่อนเลนเป้าหมายแต่ละเลน และแต่ละรอบอยู่ตรงไหนในไปป์ไลน์แบบรอบเดียวสำหรับ PHP 8.1 หรือแบบสองรอบสำหรับ PHP 7.4

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	ค่าที่ส่งคืน	ข้อยกเว้นหรือเงื่อนไขล้มเหลว	หมายเหตุ
rector/config/rector-php81.php	โครงสร้างซอร์สและรันไทม์ของ Rector	การดาวน์เกรดแบบรอบเดียวไปยังเป้าหมาย PHP 8.1	ซอร์สที่ผ่านการแปลงแล้ว	ความล้มเหลวในการแยกวิเคราะห์หรือการแปลงของ Rector	ใช้สำหรับเลนชุดแจกจ่าย PHP 8.1
rector/config/rector-php74-enums.php	โครงสร้างซอร์สและรันไทม์ของ Rector	รอบ PHP 7.4 รอบแรกสำหรับการแปลง enum	ซอร์สที่ผ่านการแปลงในขั้นกลาง	ความล้มเหลวในการแยกวิเคราะห์หรือการแปลงของ Rector	รันก่อนรอบ PHP 7.4 แบบเต็ม
rector/config/rector-php74.php	ซอร์สขั้นกลางและรันไทม์ของ Rector	รอบการดาวน์เกรด PHP 7.4 แบบเต็ม	ซอร์สที่เข้ากันได้กับ PHP 7.4	ความล้มเหลวในการแยกวิเคราะห์หรือการแปลงของ Rector	ใช้สำหรับเลนชุดแจกจ่าย PHP 7.4

กฎที่กำหนดเอง

ใช้ตารางนี้เมื่อดูแลหรือขยายกฎ Rector เฉพาะโปรเจกต์ทั้งสามกฎ และต้องการสัญญาเมธอดของแต่ละกฎ รวมถึงไวยากรณ์ที่กฎนั้นแปลง

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	ค่าที่ส่งคืน	ข้อยกเว้นหรือเงื่อนไขล้มเหลว	หมายเหตุ
DowngradeAsymmetricVisibilityRector	พรอเพอร์ตีหรือพารามิเตอร์ที่เลื่อนระดับซึ่งใช้การมองเห็นแบบไม่สมมาตร	การมองเห็นแบบธรรมดาที่เข้ากันได้กับรันไทม์รุ่นเก่า	รักษาการมองเห็นสำหรับการอ่านไว้เมื่อทำได้	ความล้มเหลวของกฎ Rector	ข้อจำกัดของ setter มีผลเฉพาะตอนคอมไพล์เท่านั้นและจะถูกลบออกในเอาต์พุตที่สร้างขึ้น
DowngradeAsymmetricVisibilityRector::getRuleDefinition()	ไม่มี	ส่งคืนข้อมูลเมตาและตัวอย่างของกฎ Rector	RuleDefinition	ไม่คาดว่าจะมี	ทำให้เอกสารของกฎปรากฏต่อเครื่องมือของ Rector
DowngradeAsymmetricVisibilityRector::getNodeTypes()	ไม่มี	เลือกชนิดโหนดที่กฎตรวจสอบ	array<class-string<Node>>	ไม่คาดว่าจะมี	ขอบเขตควรแคบไว้เพื่อให้การแปลงกำหนดผลได้แน่นอน
DowngradeAsymmetricVisibilityRector::refactor(Node $node)	โหนด AST	แปลงการมองเห็นแบบไม่สมมาตรในจุดที่ปรากฏ	`Node	null`	ความล้มเหลวของกฎ Rector
DowngradeCloneWithRector	clone() พร้อมการแทนที่ค่าพรอเพอร์ตี	การโคลนพร้อมกำหนดค่าพรอเพอร์ตีอย่างชัดเจน	ใช้ตัวแปรชั่วคราวที่สร้างขึ้น	ความล้มเหลวของกฎ Rector	ต้องรันหลังจากการดาวน์เกรดพรอเพอร์ตีแบบ readonly
DowngradeCloneWithRector::getRuleDefinition()	ไม่มี	ส่งคืนข้อมูลเมตาและตัวอย่างของกฎ	RuleDefinition	ไม่คาดว่าจะมี	ใช้โดยการวินิจฉัยของ Rector
DowngradeCloneWithRector::getNodeTypes()	ไม่มี	เลือกโหนด return และนิพจน์	array<class-string<Node>>	ไม่คาดว่าจะมี	ทำให้กฎมุ่งเน้นที่ไวยากรณ์ clone-with
DowngradeCloneWithRector::refactor(Node $node)	โหนด AST	เขียน clone-with ใหม่เป็นการโคลนพร้อมการกำหนดค่า	`array	null`	ความล้มเหลวของกฎ Rector
DowngradeTraitConstantsRector	ค่าคงที่ของ trait และการอ้างอิงถึงค่าเหล่านั้น	พรอเพอร์ตีแบบ static และการอ้างอิงพรอเพอร์ตี	รักษาการมองเห็นไว้เมื่อทำได้	ความล้มเหลวของกฎ Rector	ลบ final ออกเพราะพรอเพอร์ตีในรุ่นเก่าไม่สามารถเป็น final ได้
DowngradeTraitConstantsRector::getRuleDefinition()	ไม่มี	ส่งคืนข้อมูลเมตาและตัวอย่างของกฎ	RuleDefinition	ไม่คาดว่าจะมี	ใช้โดยการวินิจฉัยของ Rector
DowngradeTraitConstantsRector::getNodeTypes()	ไม่มี	เลือกโหนด trait และ class-constant-fetch	array<class-string<Node>>	ไม่คาดว่าจะมี	จำกัดกฎไว้เฉพาะค่าคงที่ของ trait
DowngradeTraitConstantsRector::refactor(Node $node)	โหนด AST	เขียนค่าคงที่ของ trait และการอ้างอิงใหม่ให้เป็นพรอเพอร์ตีที่เข้ากันได้	`Node	null`	ความล้มเหลวของกฎ Rector

สัญญาของแพ็กเกจที่สร้างขึ้น

ใช้ตารางนี้เพื่อดูสิ่งที่ตัวบิลเดอร์สร้างออกมา ได้แก่ ชื่อแพ็กเกจที่โปรเจกต์ปลายทางติดตั้ง และแพ็กเกจที่บรรจุชุดแจกจ่าย Pro

แพ็กเกจที่สร้างขึ้น	บทบาทในรันไทม์	หมายเหตุ
nextpdf/backport	ชุดแจกจ่ายรันไทม์แบบโอเพนซอร์สที่สร้างขึ้น	แทนที่แพ็กเกจ nextpdf/* ที่เลือกไว้สำหรับรันไทม์เป้าหมาย
nextpdf/backport-pro	ชุดแจกจ่าย Pro แบบกรรมสิทธิ์ที่สร้างขึ้นเมื่อมีซอร์ส Pro	เผยแพร่แยกจากแพ็กเกจโอเพนซอร์ส

หมายเหตุสำหรับการพัฒนา

• ตัวบิลเดอร์รับรุ่นซอร์สที่เผยแพร่เป็นอินพุตและสร้างอาร์ติแฟกต์ออกมา อย่าแก้ไขเอาต์พุตที่สร้างขึ้นโดยถือเป็นแหล่งอ้างอิงหลัก
• กฎแบบกำหนดเองแต่ละกฎต้องมีการทดสอบแบบ fixture ก่อนเข้าสู่ไปป์ไลน์การบิลด์
• งานเผยแพร่รุ่นต้องตรวจสอบเอาต์พุตที่สร้างขึ้นบนรันไทม์เป้าหมาย ไม่ใช่เฉพาะบนโฮสต์ที่ใช้บิลด์เท่านั้น