การกำหนดค่า NextPDF Backport Builder

เครื่องมือสำหรับการบิลด์ — ไม่ใช่ dependency ขณะรันไทม์ ทุกอย่างในหน้านี้ใช้กำหนดค่าการแปลงซอร์สระหว่างเวลาบิลด์ ไม่มีส่วนใดถูกส่งต่อไปยังรันไทม์ปลายทาง

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

ไฟล์การกำหนดค่า Rector สามไฟล์ภายใต้ rector/config/ และกฎแบบกำหนดเองสามกฎภายใต้ rector/rules/ เป็นกลไกหลักของการแปลง การกำหนดค่าที่ใช้ขึ้นอยู่กับเป้าหมาย เป้าหมาย PHP 8.1 ใช้การประมวลผล Rector เพียงรอบเดียว ส่วนเป้าหมาย PHP 7.4 ใช้ไปป์ไลน์สองรอบพร้อมขั้นตอนแก้ไขเพิ่มเติมระหว่างรอบ ต้องมีรอบที่สองเนื่องจาก Rector ไม่สามารถแก้ค่าเริ่มต้นของ enum case ในรอบ traverse ครั้งเดียวได้

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

ไฟล์	วัตถุประสงค์	ใช้โดย
rector/config/rector-php81.php	downgrade แบบรอบเดียวเป็น PHP 8.1	เป้าหมาย PHP 8.1
rector/config/rector-php74-enums.php	รอบที่ 1 — แปลง enum เป็นคลาสรายการค่าคงที่	เป้าหมาย PHP 7.4
rector/config/rector-php74.php	รอบที่ 2 — downgrade เต็มรูปแบบเป็น PHP 7.4	เป้าหมาย PHP 7.4

การกำหนดค่าแต่ละชุดเรียกใช้ downgrade-set chain ของ Rector (withDowngradeSets(php81: true) หรือ withDowngradeSets(php74: true)) เพื่อจัดการฟีเจอร์ที่ Rector รองรับโดยตรง จากนั้นลงทะเบียนกฎแบบกำหนดเองสำหรับฟีเจอร์ที่เหลือ ข้อมูลนี้ตรวจสอบเทียบกับไฟล์ทั้งสามใน rector/config/ แล้ว

กฎการข้าม

ทั้ง rector-php81.php และ rector-php74.php ข้าม */tests/Benchmark/* สคริปต์เบนช์มาร์กอ้างอิงไลบรารี Portable Document Format (PDF) ภายนอกที่ Rector แก้ไขไม่ได้ และทำให้ตัวแก้ค่าพารามิเตอร์เริ่มต้นของ Rector ล่ม นอกจากนี้ rector-php74.php ยังข้าม DowngradeHashAlgorithmXxHashRector ด้วย เนื่องจากกฎในตัวนี้ล่มเมื่อพบค่าคงที่ MHASH_XXH* ที่ถูกเลิกใช้ใน PHP รุ่นใหม่ ขณะที่ซอร์สไม่ได้ใช้ xxHash ข้อมูลนี้ตรวจสอบเทียบกับการเรียก withSkip() ในไฟล์ทั้งสองแล้ว

กฎแบบกำหนดเองทั้งสาม

ที่เก็บนี้มีกฎ Rector แบบกำหนดเองสามกฎพอดี ทั้งสามกฎลงทะเบียนอยู่ใน rector-php81.php ส่วนกฎ asymmetric-visibility, clone-with และ trait-constants ยังลงทะเบียนอยู่ใน rector-php74.php ด้วย tests/Rector/RectorRulesMetadataTest.php ยืนยันเรื่องนี้โดยตรง โดยสร้างกฎแต่ละกฎและตรวจสอบนิยามกับชนิดของโหนด

DowngradeAsymmetricVisibilityRector

ลบตัวปรับ set ของ asymmetric-visibility พร็อพเพอร์ตีหรือพารามิเตอร์แบบ promoted ที่ประกาศเป็น public private(set) จะกลายเป็น public ตามปกติ การเข้าถึงเพื่ออ่านยังคงอยู่ แต่ข้อจำกัดของ setter ในเวลาคอมไพล์จะถูกตัดออก หากไม่เหลือ visibility สำหรับการอ่าน กฎจะใช้ค่าเริ่มต้นเป็น public ตัวอย่างการแปลงอิงจากซอร์สใน tests/Rector/Fixtures/DowngradeAsymmetricVisibility/public_private_set.php.inc:

before

<?php

class Config {
    public private(set) float $x = 0.0;
    public private(set) string $name = '';
    public private(set) int $count = 0;
}

after

<?php

class Config {
    public float $x = 0.0;
    public string $name = '';
    public int $count = 0;
}

DowngradeCloneWithRector

เขียนรูปแบบฟังก์ชัน clone() ที่รับอาร์เรย์ของค่าทับใหม่ ให้กลายเป็นการ clone ตามด้วยการกำหนดค่าพร็อพเพอร์ตีอย่างชัดเจน และการ return ตัวแปรชั่วคราว ตัวนับตัวแปรชั่วคราวจะรีเซ็ตต่อไฟล์ กฎนี้ต้องทำงานหลังจากกฎที่ลบพร็อพเพอร์ตีแบบ readonly เพราะไม่เช่นนั้นการกำหนดค่าที่ขยายออกมาจะล้มเหลวกับพร็อพเพอร์ตีแบบ readonly ตัวอย่างการแปลงอิงจากซอร์สใน tests/Rector/Fixtures/DowngradeCloneWith/return_clone_with.php.inc:

before

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self {
        return clone($this, ['width' => $width, 'height' => $height]);
    }
}

after

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self
    {
        $__cloneResult1 = clone $this;
        $__cloneResult1->width = $width;
        $__cloneResult1->height = $height;
        return $__cloneResult1;
    }
}

กฎนี้มีข้อจำกัดที่บันทึกไว้แล้ว การจับคู่อาร์กิวเมนต์ไม่ทำงานแบบเรียกซ้ำ ดังนั้นค่าทับใหม่ที่มีวงเล็บซ้อนกันจะไม่ได้รับการจัดการ เฉพาะคีย์อาร์เรย์ที่เป็นสตริงเท่านั้นที่จะถูกแปลงเป็นชื่อพร็อพเพอร์ตี ข้อมูลนี้ตรวจสอบเทียบกับ rector/rules/DowngradeCloneWithRector.php และชุด fixture ของกฎนี้แล้ว

DowngradeTraitConstantsRector

แปลงค่าคงที่ของ trait เป็นพร็อพเพอร์ตีแบบสแตติก รันไทม์รุ่นก่อนหน้าปฏิเสธค่าคงที่ของ trait ด้วยข้อความ “Traits cannot have constants” กฎนี้ยังเขียนการอ้างอิง self::CONST และ static::CONST ใหม่เป็นรูปแบบพร็อพเพอร์ตีแบบสแตติกอีกด้วย visibility ยังคงเดิม ส่วนตัวปรับ final จะถูกตัดออกเพราะพร็อพเพอร์ตีในเป้าหมายรุ่นเก่าไม่สามารถเป็น final ได้ ค่าคงที่ของคลาสที่มีชนิดกำกับจะกลายเป็นพร็อพเพอร์ตีที่มีชนิดกำกับ ตัวอย่างการแปลงอิงจากซอร์สใน tests/Rector/Fixtures/DowngradeTraitConstants/private_constant.php.inc:

before

<?php

trait HasLimit
{
    private const MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::MAX_SIZE;
    }
}

after

<?php

trait HasLimit
{
    private static $MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::$MAX_SIZE;
    }
}

ไปป์ไลน์ PHP 7.4 แบบสองรอบ

เป้าหมาย PHP 7.4 ไม่สามารถประมวลผลให้เสร็จในรอบเดียวได้ ตัวแก้ค่าพารามิเตอร์เริ่มต้นของ Rector จะล่มเมื่อพบค่าเริ่มต้นของ enum case ใน constructor promotion สคริปต์การบิลด์จึงทำงานตามลำดับนี้:

1. รอบที่ 1 — การประมวลผล enum ล่วงหน้า rector-php74-enums.php รันเฉพาะกฎในตัวที่แปลง enum เป็นคลาสรายการค่าคงที่เท่านั้น หลังจบรอบนี้ enum case จะกลายเป็นค่าคงที่ของคลาสธรรมดา
2. ล้างแคช แคชของ Rector จะถูกล้างเพื่อให้รอบที่สองไม่เห็นทรีเก่าที่ค้างอยู่
3. การแก้ไขหลังการประมวลผล scripts/build.php เขียนรูปแบบที่กฎแปลง enum เป็นคลาสยังครอบคลุมไม่ถึงใหม่ เมธอดอินสแตนซ์ของ enum เดิมจะกลายเป็นเมธอดสแตติก การเข้าถึง EnumClass::Case->value และ ->name จะได้รับการแก้ค่า อาร์กิวเมนต์แบบมีชื่อที่ Rector ผูกไม่ได้จะถูกแปลงเป็นอาร์กิวเมนต์ตามตำแหน่ง หากไม่แก้ไข รูปแบบไวยากรณ์เหล่านี้จะทำให้เกิด parse error บน PHP 7.4
4. รอบที่ 2 — การลด downgrade เต็มรูปแบบ rector-php74.php รัน downgrade chain ของ PHP 7.4 แบบเต็มพร้อมกฎแบบกำหนดเอง

ข้อมูลนี้ตรวจสอบเทียบกับ scripts/build.php (runRector(), postProcessFixups()) แล้ว

ข้อมูลอ้างอิงแฟล็กการบิลด์

scripts/build.php เป็นตัวประสานการบิลด์ รายการตัวเลือกของสคริปต์นี้ตรวจสอบเทียบกับการเรียก getopt() และ constructor ของ Build แล้ว:

แฟล็ก	ค่าเริ่มต้น	ผลลัพธ์
--version=<x.y.z>	2.0.0	เวอร์ชันที่จะเขียนลงในไฟล์ที่สร้างขึ้น composer.json และ CHANGELOG.md
--source-dir=<path>	c:/Users/admin/Documents	รูตที่มีที่เก็บซอร์สซึ่งเป็น sibling
--output-dir=<path>	<repo>/output	ตำแหน่งสำหรับเขียนแพ็กเกจการแจกจ่ายที่สร้างขึ้น
--target=php74 | --target=php81	php81	เป้าหมายการ downgrade โดย php74 บังคับให้ใช้เฉพาะ core และปิดใช้งาน Pro
--dry-run	ปิด	รันทุกขั้นตอนในโหมดรายงานเท่านั้น โดยข้ามการคัดลอกและ Rector
--no-pro	ปิด	ยกเว้นแพ็กเกจ Pro (ใช้กับเป้าหมาย PHP 8.1 เท่านั้น ส่วน PHP 7.4 ยกเว้นอยู่แล้ว)

ค่า --target ที่ไม่ถูกต้องจะทำให้เกิด InvalidArgumentException ก่อนเริ่มงานใดๆ ข้อมูลนี้ตรวจสอบเทียบกับ Build::__construct() (การป้องกันด้วย VALID_TARGETS) แล้ว

สคริปต์ Composer

สคริปต์	คำสั่ง	วัตถุประสงค์
composer test	phpunit	รันชุด fixture ของกฎ
composer analyse	phpstan analyse rector/rules scripts --level=10	วิเคราะห์โค้ดการบิลด์แบบสแตติก
composer build	php scripts/build.php	บิลด์เต็มรูปแบบ
composer build:dry	php scripts/build.php --dry-run	การบิลด์แบบ dry-run

ข้อมูลนี้ตรวจสอบเทียบกับ composer.jsonscripts แล้ว

ถัดไป

• /integrations/backport/quickstart/ — รัน dry-run และบิลด์เต็มรูปแบบ
• /integrations/backport/troubleshooting/ — อธิบายความหมายของแต่ละขั้นตอนที่ล้มเหลว