กฎความเสถียรของ SPI

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

service provider interface ของ NextPDF ใช้ Semantic Versioning สัญญาสาธารณะแต่ละรายการมีแท็ก @stability และคำมั่นเรื่องความเข้ากันได้ย้อนหลัง ใช้กฎเหล่านี้เพื่อตัดสินใจว่าสัญญาใดที่คุณสามารถพึ่งพาได้

การติดตั้ง

composer require nextpdf/core:^3

ภาพรวมเชิงแนวคิด

service provider interface ครอบคลุมสัญญาสาธารณะในเนมสเปซ NextPDF\Contracts และ NextPDF\Event ชนิดข้อมูลจะถือเป็นส่วนหนึ่งของอินเทอร์เฟซก็ต่อเมื่อ PHPDoc ในซอร์สมีแท็ก @stability แท็กนี้เป็นตัวกำหนดขอบเขต ชนิดข้อมูลที่ไม่มีแท็กถือเป็นชนิดภายใน แม้ PHP จะเปิดเผยเป็น public ก็ตาม

NextPDF เป็นไปตาม Semantic Versioning 2.0.0 การเปลี่ยนแปลงที่ทำให้เกิดความไม่เข้ากันกับสัญญา stable ต้องเพิ่มเวอร์ชันหลัก สัญญาใหม่หรือการเพิ่มที่ไม่ทำให้เกิดความไม่เข้ากันจะเพิ่มเวอร์ชันรอง การแก้ไขข้อบกพร่องจะเพิ่มเวอร์ชันแพตช์

แท็ก @stability

สัญญาแต่ละรายการประกาศค่าความเสถียรได้หนึ่งในสามค่านี้:

แท็ก	ความหมาย	กฎการเปลี่ยนแปลง
stable	พร้อมสำหรับการใช้งานจริง และสามารถพึ่งพาได้อย่างปลอดภัย	ไม่มีการเปลี่ยนแปลงที่ทำให้เกิดความไม่เข้ากันในเวอร์ชันรองหรือเวอร์ชันแพตช์ เมธอดใหม่จะเพิ่มเฉพาะเมื่อมีพฤติกรรมค่าเริ่มต้นหรือเพิ่มบนสัญญาใหม่เท่านั้น
experimental	ใช้งานได้ แต่ยังไม่ได้ตรึงสัญญา	อินเทอร์เฟซอาจเปลี่ยนแปลงได้ในเวอร์ชันรอง โดยจะมีประกาศการเลิกใช้งานก่อน
deprecated	มีกำหนดถอดออก	สัญญาระบุรายการทดแทนและเวอร์ชันที่จะถอดออก

NextPDF บันทึกคำมั่นของแต่ละสัญญาไว้ในแมปสัญญาที่สร้างขึ้น และสร้างแมปนั้นใหม่จากซอร์สในทุกรุ่นที่ออก ข้อความคำมั่นระบุกฎที่แม่นยำสำหรับสัญญานั้น ให้ถือว่า PHPDoc ในซอร์สของสัญญาเป็นแหล่งความจริงเพียงแหล่งเดียว

คลาสคำมั่นเรื่องความเข้ากันได้ย้อนหลัง

แมปสัญญาบันทึกคำมั่นแต่ละรายการไว้ในหนึ่งในสี่คลาส:

1. คำมั่นของอินเทอร์เฟซ “ไม่มีการเปลี่ยนแปลงที่ทำให้เกิดความไม่เข้ากันในเวอร์ชันรองหรือเวอร์ชันแพตช์ เมธอดใหม่จะมีได้เฉพาะเมื่อมีการนำไปใช้แบบค่าเริ่มต้นเท่านั้น” ใช้กับอินเทอร์เฟซ stable ส่วนใหญ่ รวมถึง FontRegistryInterface, SignerInterface, HsmSignerInterface และ HtmlSecurityPolicyInterface เป็นต้น
2. คำมั่นของ enum “ไม่มีการถอด case ออก อาจเพิ่ม case ใหม่ได้ในเวอร์ชันรอง” ใช้กับ enum แบบ stable เช่น Alignment, Orientation และ OutputDestination เป็นต้น
3. คำมั่นของ value object ที่ตรึง “ลายเซ็นของคอนสตรัคเตอร์และคุณสมบัติสาธารณะถูกตรึงไว้ อาจเพิ่มเมธอดใหม่ได้” ใช้กับ value object เช่น TextPreprocessResult, TextSegment และ event payload ที่เกี่ยวข้อง
4. คำมั่นของ experimental “อินเทอร์เฟซอาจเปลี่ยนแปลงได้ในเวอร์ชันรองโดยจะมีประกาศการเลิกใช้งาน” ใช้กับสัญญาแบบ experimental เช่น DeferredSignerInterface, TimestampProviderInterface, CursorInterface และ StreamingWriterInterface เป็นต้น

คลาส final เช่น EventDispatcher หรือ ListenerProvider จะตรึงลายเซ็นของเมธอดสาธารณะไว้ ใช้การประกอบ (composition) เพื่อขยายคลาส final อย่าสร้างคลาสย่อย

สัญญาสตรีมมิงแบบ experimental

CursorInterface และ StreamingWriterInterface เป็นแบบ experimental (ตั้งแต่ 3.1.0) NextPDF จัดส่งการนำสัญญาทั้งสองไปใช้ในระดับเอนจินที่ผ่านการทดสอบและเป็น final คลาสที่นำไปใช้เป็นคลาสภายในและไม่เป็นส่วนหนึ่งของพื้นผิวสาธารณะ คุณใช้พฤติกรรมสตรีมมิงผ่านสัญญา experimental สาธารณะ โดยทั่วไปคุณไม่จำเป็นต้องนำสัญญาเหล่านี้ไปใช้เอง

เนื่องจากสัญญาเป็นแบบ experimental ลายเซ็นของสัญญาอาจเปลี่ยนแปลงได้ในเวอร์ชันรอง โดยจะมีประกาศการเลิกใช้งานก่อน (คำมั่นของ experimental) ก่อนพึ่งพาในการใช้งานจริง ให้ตรึงเวอร์ชันอย่างเข้มงวดหรือห่อหุ้มไว้หลังอะแดปเตอร์ของคุณเอง ให้ถือว่าสัญญาสตรีมมิงเป็นจุดขยายที่กำลังมุ่งสู่ความเสถียร ไม่ใช่จุดขยายที่ตรึงแล้ว

พื้นผิว API

หน้านี้ไม่มี application programming interface (API) สำหรับรันไทม์ พื้นผิวที่เกี่ยวข้องคือแท็ก PHPDoc @stability บนสัญญาสาธารณะทุกรายการ และแมปสัญญาที่สร้างใหม่ซึ่งรวบรวมคำมั่นของแต่ละสัญญา

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

อ่านค่าความเสถียรของสัญญาจากซอร์สก่อนพึ่งพาสัญญานั้น

<?php

declare(strict_types=1);

use ReflectionClass;

$doc = (new ReflectionClass(\NextPDF\Contracts\FontRegistryInterface::class))
    ->getDocComment();

// Look for the "@stability stable" line in the contract PHPDoc.
\assert(\is_string($doc) && \str_contains($doc, '@stability stable'));

ตัวอย่างโค้ด — การใช้งานจริง

ข้อจำกัดเวอร์ชันของ Composer จะตรึงเวอร์ชันหลัก ซึ่งเป็นจุดที่สัญญา stable จะมีการเปลี่ยนแปลงที่ทำให้เกิดความไม่เข้ากัน

{
    "require": {
        "nextpdf/core": "^3.0"
    }
}

ใช้ ^3.0 เพื่อรับเวอร์ชันรองและเวอร์ชันแพตช์โดยไม่มีการเปลี่ยนแปลงที่ทำให้เกิดความไม่เข้ากันกับสัญญา stable ใดๆ ตรึงเวอร์ชันให้เข้มงวดมากขึ้นเมื่อคุณพึ่งพาสัญญาแบบ experimental เนื่องจากสัญญาแบบ experimental อาจเปลี่ยนแปลงได้ในเวอร์ชันรอง

กรณีขอบเขตและข้อควรระวัง

• แท็ก ไม่ใช่การมองเห็น เมธอด PHP ที่ทำเครื่องหมายเป็น public ไม่ได้เป็นส่วนหนึ่งของ service provider interface เว้นแต่ชนิดข้อมูลที่ประกาศเมธอดนั้นจะมีแท็ก @stability กำกับอยู่
• ความเปลี่ยนแปลงของ experimental สัญญาแบบ experimental อาจเปลี่ยนแปลงได้ในเวอร์ชันรอง ตรึงเวอร์ชันอย่างเข้มงวดหรือห่อหุ้มไว้หลังอะแดปเตอร์ของคุณเอง ข้อนี้ใช้กับสัญญาสตรีมมิงแม้จะมีการจัดส่งการนำไปใช้แล้วก็ตาม
• เมธอดค่าเริ่มต้นใหม่ อินเทอร์เฟซแบบ stable อาจมีการเพิ่มเมธอดที่มีพฤติกรรมค่าเริ่มต้น นำเมธอดใหม่ไปใช้เมื่อคุณอัปเกรด เพื่อให้การนำไปใช้ของคุณเองยังคงชัดเจน
• ความเท่าเทียมระหว่างรุ่นผลิตภัณฑ์ NextPDF Pro และ NextPDF Enterprise เป็นไปตามกฎเดียวกัน สัญญาที่คุณกำหนดเป้าหมายใน Core ยังคงใช้ได้กับการนำสัญญาเดียวกันไปใช้ในเวอร์ชัน Premium

วงจรชีวิตของการเลิกใช้งาน

สัญญาจะผ่านวงจรชีวิตที่กำหนดไว้ดังนี้:

1. ทำเครื่องหมาย เจ้าของกำหนด @stability deprecated ใน PHPDoc ของซอร์ส และบันทึกรายการทดแทนกับเวอร์ชันที่จะถอดออก
2. ประกาศ การเลิกใช้งานจะถูกประกาศใน changelog สำหรับรุ่นที่ทำเครื่องหมายไว้
3. ช่วงทับซ้อน สัญญาที่เลิกใช้งานและรายการทดแทนจะอยู่ร่วมกันเป็นเวลาอย่างน้อยหนึ่งเวอร์ชันรอง
4. ถอดออก สัญญาจะถูกถอดออกในเวอร์ชันหลักที่ระบุไว้ การถอดออกจะไม่เกิดขึ้นในเวอร์ชันรองหรือเวอร์ชันแพตช์

วางแผนการอัปเกรดทันทีที่สัญญาถูกทำเครื่องหมายเป็น deprecated ระบุรายการทดแทนไว้เสมอ

ประสิทธิภาพ

หน้านี้กำหนดนโยบายเท่านั้น ไม่มีต้นทุนในรันไทม์

หมายเหตุด้านความปลอดภัย

สัญญาการลงนามเป็นแบบ stable และเป็นไปตามคำมั่นของอินเทอร์เฟซ เมธอดใหม่ในสัญญาการลงนามจะเพิ่มได้เฉพาะเมื่อมีพฤติกรรมค่าเริ่มต้น หรือเพิ่มบนสัญญาใหม่เท่านั้น ดังนั้นการนำไปใช้ที่มีฮาร์ดแวร์รองรับจะไม่เสียความเข้ากันได้เมื่ออัปเกรดเวอร์ชันรอง ตรวจสอบ changelog ก่อนการอัปเกรดเวอร์ชันหลัก เนื่องจากเวอร์ชันหลักอาจเปลี่ยนแปลงสัญญาแบบ stable ได้

ความสอดคล้อง

กฎการกำหนดเวอร์ชันเหล่านี้สอดคล้องกับ Semantic Versioning 2.0.0 การสร้าง changelog เป็นไปตาม Conventional Commits 1.0.0

บริบทเชิงพาณิชย์

NextPDF Pro และ NextPDF Enterprise เป็นไปตามกฎความเสถียรของ service provider interface เดียวกันกับ Core สัญญาที่คุณกำหนดเป้าหมายใน Core ยังคงใช้ได้กับการนำสัญญานั้นไปใช้ในเวอร์ชัน Premium ดังนั้นโค้ดส่วนขยายของคุณจึงใช้ข้ามรุ่นผลิตภัณฑ์ได้

ดูเพิ่มเติม

• ภาพรวมการสร้างส่วนขยาย
• ฟอนต์ที่กำหนดเอง
• ทริกเกอร์การดำเนินการและตัวรับฟังเหตุการณ์
• สัญญาผู้ให้บริการ KMS

สัญญาและโมดูลที่เกี่ยวข้อง

• เอกสารอ้างอิงโมดูลสัญญา — แมปสัญญาที่สร้างขึ้นและข้อความคำมั่นของแต่ละสัญญา
• เอกสารอ้างอิงสัญญาสตรีมมิง — สัญญาสตรีมมิงแบบ experimental และการนำไปใช้ที่จัดส่งมาพร้อมกัน
• เอกสารอ้างอิงสัญญาการลงนาม — สัญญาการลงนามแบบ stable และ experimental ภายใต้กฎเดียวกัน
• ภาพรวมการสร้างส่วนขยาย — ความหมายของแท็ก @stability แต่ละแบบในทางปฏิบัติ
• ทริกเกอร์การดำเนินการและตัวรับฟังเหตุการณ์ — ตัวจัดส่ง final และ payload แบบ experimental ที่กฎเหล่านี้กำกับดูแล

อภิธานศัพท์ให้คำนิยามของคำว่า แท็กความเสถียร และ คำมั่นเรื่องความเข้ากันได้ย้อนหลัง ดูคำนิยามตามมาตรฐานได้ในอภิธานศัพท์ที่เผยแพร่