การพัฒนาส่วนขยาย: ภาพรวม SPI สาธารณะ

โดยสรุป

NextPDF เปิดเผยสัญญาสาธารณะชุดเล็กที่กำหนดไว้อย่างตั้งใจภายใต้เนมสเปซ NextPDF\Contracts และ NextPDF\Event คุณนำสัญญาเหล่านี้ไปใช้งานได้เพื่อเพิ่มฟอนต์ ดักจับข้อความ สังเกตวงจรชีวิตของเอกสาร หรือจัดเตรียม back end สำหรับการลงลายเซ็นของคุณเอง โดยไม่ต้องแยกเอนจินออกเป็นสาขา (fork)

การติดตั้ง

composer require nextpdf/core:^3

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

NextPDF แยก public service provider interface (SPI) ออกจากโค้ดภายในอย่างชัดเจน SPI คือชุดของชนิดข้อมูลที่คุณสามารถนำไปใช้งานหรือสังเกตได้ ส่วนอื่นทั้งหมดเป็น private และอาจเปลี่ยนแปลงได้โดยไม่แจ้งให้ทราบล่วงหน้า

SPI สาธารณะมีสามรูปแบบดังนี้

สัญญา registry บริการที่คงอยู่ตลอดอายุของกระบวนการ (process-lifetime) ซึ่งคุณกำหนดค่าก่อนสร้างเอกสาร โดย FontRegistryInterface และ ImageRegistryInterface เป็นตัวอย่างหลัก ให้ลงทะเบียนแอสเซต แล้วเอนจินจะอ่านแอสเซตเหล่านั้น
สัญญา strategy hook สำหรับงานเดี่ยวที่เอนจินเรียกใช้ระหว่างการเรนเดอร์ TextPreprocessorInterface จัดการการดักจับข้อความในช่วงการจัดวาง (layout-time) และ HtmlSecurityPolicyInterface ควบคุมการเปิดใช้คุณลักษณะ Hypertext Markup Language (HTML) คุณจัดเตรียมพฤติกรรม แล้วเอนจินจะเรียกใช้พฤติกรรมนั้น
สัญญาการลงลายเซ็น back end ด้านการเข้ารหัสลับสำหรับการลงลายเซ็น SignerInterface, HsmSignerInterface และ DeferredSignerInterface ช่วยให้คุณจัดเตรียมการเก็บรักษาคีย์และการสร้างลายเซ็น เอนจินสร้างโครงสร้าง Cryptographic Message Syntax (CMS) ส่วนโค้ดของคุณเป็นผู้ถือคีย์

ระบบ event แยกต่างหากใน NextPDF\Event เข้ากันได้กับ PHP Standard Recommendation 14 (PSR-14) และใช้จัดการการสังเกตการณ์ event ของวงจรชีวิต ช่วยให้คุณตอบสนองต่อการสร้างเอกสาร หน้าใหม่ การโหลดฟอนต์ การลงลายเซ็น และการเขียนผลลัพธ์ event เหล่านี้ไม่เปลี่ยนแปลงพฤติกรรมของเอนจิน

สัญญาแต่ละรายการมีแท็ก @stability อยู่ใน PHPDoc ของซอร์ส ได้แก่ stable, experimental หรือ deprecated แท็กนี้และคำมั่นด้านความเข้ากันได้ย้อนหลังของแต่ละสัญญาช่วยบอกว่าควรคาดหวังการเปลี่ยนแปลงมากน้อยเพียงใด ดู กฎความเสถียรของ SPI สำหรับนโยบายฉบับเต็ม

สิ่งใดที่ขยายได้

ความสามารถ	สัญญาสาธารณะ	ความเสถียร
การลงทะเบียนและการค้นหาฟอนต์	`NextPDF\Contracts\FontRegistryInterface`	stable (ตั้งแต่ 1.7.0)
การแคชและการถอดรหัสรูปภาพ	`NextPDF\Contracts\ImageRegistryInterface`	stable (ตั้งแต่ 2.0.0)
การดักจับข้อความในช่วงการจัดวาง	`NextPDF\Contracts\TextPreprocessorInterface`	stable (ตั้งแต่ 1.9.0)
การควบคุมการเปิดใช้คุณลักษณะ HTML	`NextPDF\Contracts\HtmlSecurityPolicyInterface`	stable (ตั้งแต่ 3.1.0)
การต่อเชื่อม document factory	`NextPDF\Contracts\DocumentFactoryInterface`	stable (ตั้งแต่ 1.7.0)
การลงลายเซ็นแบบซิงโครนัส	`NextPDF\Contracts\SignerInterface`	stable (ตั้งแต่ 1.0.0)
การลงลายเซ็นที่รองรับด้วยฮาร์ดแวร์	`NextPDF\Contracts\HsmSignerInterface`	stable (ตั้งแต่ 1.0.0)
การลงลายเซ็นแบบหน่วงเวลาและแบบกลุ่ม	`NextPDF\Contracts\DeferredSignerInterface`	experimental (ตั้งแต่ 3.0.0)
การประทับเวลาตาม RFC 3161	`NextPDF\Contracts\TimestampProviderInterface`	experimental (ตั้งแต่ 3.0.0)
การสังเกตการณ์วงจรชีวิต	`NextPDF\Event\*` (เข้ากันได้กับ PSR-14)	dispatcher เป็น stable; payload เป็น experimental

สิ่งใดที่ไม่ใช่สาธารณะ

ชนิดข้อมูลต่อไปนี้เป็นข้อมูลภายใน อย่า import สร้างคลาสย่อย (subclass) หรือพึ่งพาชนิดข้อมูลเหล่านี้

คลาสใดก็ตามที่อยู่นอกเนมสเปซ NextPDF\Contracts และ NextPDF\Event เว้นแต่ PHPDoc ของคลาสนั้นจะมีแท็ก @stability กำกับไว้
โค้ดเอนจินที่เป็น implementation จริง รวมถึงตัวแยกวิเคราะห์ HTML ตัวเขียน (writer) ไปป์ไลน์การจัดวาง และตัวสร้างชุดย่อยฟอนต์ (font subsetter)
แพ็กเกจ NextPDF Pro และ NextPDF Enterprise คลาสภายในของแพ็กเกจเหล่านี้ไม่ได้เป็นส่วนหนึ่งของพื้นผิวโอเพนซอร์ส เมื่อรุ่นที่มีค่าใช้จ่ายมาพร้อมการนำ SPI ไปใช้งาน ให้ใช้สัญญาสาธารณะ ไม่ใช่ชนิดข้อมูลภายในของรุ่นนั้น

พื้นผิว API

แผนผังสัญญาที่สร้างขึ้นเป็นแหล่งข้อมูลที่เชื่อถือได้ และจะสร้างใหม่จากซอร์สในทุกรุ่นที่ออก ให้ถือว่าแท็ก PHPDoc @stability ในไฟล์ interface แต่ละไฟล์เป็นแหล่งข้อมูลที่ถูกต้องเพียงแหล่งเดียว ใช้ตารางด้านบนเป็นตัวช่วยประกอบการอ่าน

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

ลงทะเบียนฟอนต์ จากนั้นสังเกตการโหลดฟอนต์นั้น ทั้งสองขั้นตอนใช้เฉพาะชนิดข้อมูลสาธารณะเท่านั้น

<?php

declare(strict_types=1);

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Event\Content\FontLoadedEvent;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;

/** @var FontRegistryInterface $fonts */
$fonts->register('/srv/fonts/Inter-Regular.ttf', 'Inter');

$listeners = new ListenerProvider();
$listeners->addListener(
    FontLoadedEvent::class,
    static function (FontLoadedEvent $event): void {
        \error_log("Font loaded: {$event->family} {$event->style}");
    },
);

$dispatcher = new EventDispatcher($listeners);

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

ใน worker ที่ทำงานต่อเนื่องเป็นเวลานาน ให้สร้าง registry เพียงครั้งเดียวขณะบูต ล็อก registry เหล่านั้น แล้วฉีด dispatcher ที่ใช้ร่วมกันผ่าน document factory

<?php

declare(strict_types=1);

use NextPDF\Contracts\DocumentFactoryInterface;
use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;
use Psr\Log\LoggerInterface;

final class DocumentBootstrap
{
    public function __construct(
        private readonly FontRegistryInterface $fonts,
        private readonly DocumentFactoryInterface $factory,
        private readonly LoggerInterface $logger,
    ) {}

    public function warmup(): EventDispatcher
    {
        $this->fonts->warmup([
            '/srv/fonts/Inter-Regular.ttf',
            '/srv/fonts/Inter-Bold.ttf',
        ]);
        $this->fonts->lock();

        $listeners = new ListenerProvider();
        $listeners->addListener(
            \NextPDF\Event\Security\SignatureAppliedEvent::class,
            fn (object $event): mixed => $this->logger->info('Signature applied'),
        );

        return new EventDispatcher($listeners);
    }
}

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

การล็อก registry หลังจาก FontRegistryInterface::lock() เมธอดที่เปลี่ยนแปลงสถานะจะโยน LogicException ให้ล็อกหลังจากการ warmup เสร็จสิ้นแล้วเท่านั้น
ระดับความเสถียรไม่ตรงกัน สัญญาแบบ experimental อาจเปลี่ยนแปลงได้ในรุ่นย่อย (minor release) ตรวจสอบระดับความเสถียรที่ระบุไว้ก่อนพึ่งพาสัญญานั้นในโปรดักชัน
วินัยด้านเนมสเปซ ชนิดข้อมูลที่อยู่นอก NextPDF\Contracts หรือ NextPDF\Event และไม่มีแท็ก @stability เป็นข้อมูลภายใน แม้ว่าในทางเทคนิคจะเป็น public ก็ตาม

ประสิทธิภาพ

SPI ไม่มีต้นทุนใดเลยเมื่อไม่ได้ใช้งาน หากไม่มี listener ผูกอยู่กับคลาส event ใด event dispatcher จะคืนค่าทันทีหลังจากตรวจสอบ hasListeners() เพียงครั้งเดียว registry เก็บข้อมูล PHP ล้วน และรองรับการ warmup ขณะบูตเพื่อกระจายความหน่วงของคำขอแรกออกไป

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

สัญญาการลงลายเซ็นเป็นพื้นผิวที่อ่อนไหวด้านความปลอดภัย HsmSignerInterface กำหนดให้คีย์ส่วนตัวต้องไม่ออกจากขอบเขตของฮาร์ดแวร์โดยเด็ดขาด การนำไปใช้งานของคุณต้องปฏิบัติตามข้อกำหนดดังกล่าว ดู สัญญาผู้ให้บริการ key management system (KMS) สำหรับสัญญา back end สำหรับการลงลายเซ็นของบุคคลที่สามและแบบจำลองภัยคุกคามของสัญญานั้น

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

หน้าภาพรวมนี้ไม่มีการกล่าวอ้างเชิงบรรทัดฐานใด ความสอดคล้องของแต่ละสัญญา รวมถึง PDF Advanced Electronic Signatures (PAdES) และการจัดการคีย์ บันทึกไว้ในหน้า SPI ที่เกี่ยวข้อง

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

NextPDF Pro และ NextPDF Enterprise จัดเตรียมการนำไปใช้งานระดับโปรดักชันของสัญญาการลงลายเซ็นและการตรวจสอบหลายรายการ รวมถึงการลงลายเซ็นที่รองรับด้วย key management system คุณจึงพึ่งพาสัญญาสาธารณะได้ ในขณะที่รุ่นเป็นผู้จัดเตรียมการนำไปใช้งาน ดังนั้นโค้ดของคุณจึงยังคงเคลื่อนย้ายได้ระหว่างรุ่นต่าง ๆ

ดูเพิ่มเติม

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

เอกสารอ้างอิงโมดูล Contracts — แผนผังสัญญาที่สร้างขึ้นฉบับเต็ม
เอกสารอ้างอิงสัญญาการลงลายเซ็น — SignerInterface, HsmSignerInterface และ DeferredSignerInterface ซึ่งเป็นอินเทอร์เฟซสำหรับการลงลายเซ็น
เอกสารอ้างอิงสัญญานโยบายความปลอดภัย — HtmlSecurityPolicyInterface โดยละเอียด
เอกสารอ้างอิงโมดูล Event — พื้นผิวการสังเกตการณ์วงจรชีวิต
กฎความเสถียรของ SPI — นโยบายการเปลี่ยนแปลงที่อยู่เบื้องหลังแท็ก @stability ทุกแท็ก
สัญญาผู้ให้บริการ KMS — สัญญา back end การลงลายเซ็นและแบบจำลองภัยคุกคาม

อภิธานศัพท์นิยาม SPI, extension point, stability tag และ backward-compatibility promise; ดูอภิธานศัพท์ที่เผยแพร่สำหรับคำจำกัดความมาตรฐานของแต่ละคำ