Viết phần mở rộng: tổng quan SPI công khai

Nhìn nhanh

NextPDF cung cấp một tập hợp nhỏ các hợp đồng công khai được chọn lọc kỹ trong các namespace NextPDF\Contracts và NextPDF\Event. Hãy triển khai các hợp đồng này để thêm phông chữ, chặn văn bản, theo dõi vòng đời tài liệu, hoặc cung cấp back end ký riêng mà không cần fork engine.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

NextPDF tách service provider interface (SPI) công khai khỏi mã nội bộ. SPI là tập hợp các kiểu mà bạn có thể triển khai hoặc theo dõi. Mọi thứ còn lại đều là nội bộ và có thể thay đổi mà không báo trước.

SPI công khai có ba dạng:

Hợp đồng registry. Các dịch vụ sống suốt vòng đời tiến trình, được bạn nạp dữ liệu trước khi tạo tài liệu; FontRegistryInterface và ImageRegistryInterface là những ví dụ chính. Bạn đăng ký tài nguyên, còn engine đọc các tài nguyên đó.
Hợp đồng strategy. Các hook làm một việc duy nhất và được engine gọi trong khi kết xuất. TextPreprocessorInterface xử lý việc chặn văn bản tại thời điểm bố cục, còn HtmlSecurityPolicyInterface kiểm soát các tính năng Hypertext Markup Language (HTML). Bạn cung cấp hành vi, còn engine gọi hành vi đó.
Hợp đồng ký. Các back end mã hóa. SignerInterface, HsmSignerInterface, và DeferredSignerInterface cho phép bạn cung cấp việc quản lý khóa và tạo chữ ký. Engine xây dựng cấu trúc Cryptographic Message Syntax (CMS), còn mã của bạn giữ khóa.

Một hệ thống sự kiện riêng trong NextPDF\Event, tương thích với PHP Standard Recommendation 14 (PSR-14), phụ trách việc theo dõi. Các sự kiện vòng đời cho phép bạn phản ứng với việc tạo tài liệu, thêm trang mới, tải phông chữ, ký, và ghi ra. Chúng không làm thay đổi hành vi của engine.

Mỗi hợp đồng có một thẻ @stability trong PHPDoc nguồn của nó: stable, experimental, hoặc deprecated. Thẻ này, cùng với cam kết tương thích ngược cho từng hợp đồng, cho bạn biết mức độ thay đổi có thể xảy ra. Xem Quy tắc ổn định của SPI để biết toàn bộ chính sách.

Những gì có thể mở rộng

Khả năng	Hợp đồng công khai	Tính ổn định
Đăng ký và tra cứu phông chữ	`NextPDF\Contracts\FontRegistryInterface`	stable (từ 1.7.0)
Lưu vào bộ nhớ đệm và giải mã hình ảnh	`NextPDF\Contracts\ImageRegistryInterface`	stable (từ 2.0.0)
Chặn văn bản tại thời điểm bố cục	`NextPDF\Contracts\TextPreprocessorInterface`	stable (từ 1.9.0)
Kiểm soát tính năng HTML	`NextPDF\Contracts\HtmlSecurityPolicyInterface`	stable (từ 3.1.0)
Tích hợp document factory	`NextPDF\Contracts\DocumentFactoryInterface`	stable (từ 1.7.0)
Ký đồng bộ	`NextPDF\Contracts\SignerInterface`	stable (từ 1.0.0)
Ký dựa trên phần cứng	`NextPDF\Contracts\HsmSignerInterface`	stable (từ 1.0.0)
Ký hoãn lại và ký hàng loạt	`NextPDF\Contracts\DeferredSignerInterface`	experimental (từ 3.0.0)
Đóng dấu thời gian RFC 3161	`NextPDF\Contracts\TimestampProviderInterface`	experimental (từ 3.0.0)
Theo dõi vòng đời	`NextPDF\Event\*` (tương thích PSR-14)	dispatcher stable; payload experimental

Những gì không công khai

Các kiểu sau đây là nội bộ. Đừng import, kế thừa, hoặc phụ thuộc vào chúng:

Bất kỳ lớp nào nằm ngoài các namespace NextPDF\Contracts và NextPDF\Event, trừ khi PHPDoc của nó có thẻ @stability.
Mã engine cụ thể, bao gồm bộ phân tích HTML, bộ ghi, đường ống bố cục, và bộ tạo tập con phông chữ.
Các gói NextPDF Pro và NextPDF Enterprise. Các lớp nội bộ trong đó không thuộc bề mặt mã nguồn mở. Khi một phiên bản trả phí cung cấp một bản triển khai SPI, hãy dùng hợp đồng công khai, không dùng kiểu nội bộ của nó.

Bề mặt API

Bản đồ hợp đồng được tạo là nguồn chính thức và được dựng lại từ mã nguồn cho mỗi bản phát hành. Hãy xem thẻ PHPDoc @stability trong từng tệp interface là nguồn thông tin chính xác duy nhất. Hãy dùng bảng phía trên như công cụ hỗ trợ đọc.

Mẫu mã — bắt đầu nhanh

Đăng ký một phông chữ rồi theo dõi thời điểm phông chữ đó được tải. Cả hai bước chỉ dùng các kiểu công khai.

<?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);

Mẫu mã — Môi trường sản xuất

Trong một worker chạy lâu dài, hãy khởi tạo các registry một lần lúc khởi động, khóa chúng lại, rồi truyền một dispatcher dùng chung qua 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);
    }
}

Trường hợp biên & điểm cần lưu ý

Khóa registry. Sau FontRegistryInterface::lock(), các phương thức thay đổi trạng thái sẽ ném LogicException. Chỉ khóa sau khi quá trình warmup hoàn tất.
Không khớp tính ổn định. Một hợp đồng experimental có thể thay đổi trong một bản phát hành nhỏ. Hãy kiểm tra mức ổn định được nêu trước khi bạn phụ thuộc vào hợp đồng đó trong môi trường sản xuất.
Kỷ luật namespace. Một kiểu nằm ngoài NextPDF\Contracts hoặc NextPDF\Event mà không có thẻ @stability thì là nội bộ, ngay cả khi về mặt kỹ thuật kiểu đó là public.

Hiệu năng

SPI không phát sinh chi phí khi không được dùng. Nếu không có listener nào được gắn cho một lớp sự kiện, event dispatcher trả về ngay sau một lần kiểm tra hasListeners() duy nhất. Các registry chứa dữ liệu PHP thuần và hỗ trợ warmup khi khởi động để dàn trải độ trễ của yêu cầu đầu tiên.

Ghi chú bảo mật

Các hợp đồng ký là bề mặt nhạy cảm về bảo mật. HsmSignerInterface yêu cầu khóa riêng không bao giờ rời khỏi ranh giới phần cứng. Bản triển khai của bạn phải tuân thủ yêu cầu đó. Xem hợp đồng nhà cung cấp key management system (KMS) để tìm hiểu hợp đồng back end ký của bên thứ ba và mô hình mối đe dọa tương ứng.

Sự tuân thủ

Trang tổng quan này không đưa ra tuyên bố mang tính quy chuẩn nào. Mức tuân thủ của từng hợp đồng, bao gồm PDF Advanced Electronic Signatures (PAdES) và quản lý khóa, được ghi lại trên các trang SPI liên quan.

Bối cảnh thương mại

NextPDF Pro và NextPDF Enterprise cung cấp các bản triển khai sẵn sàng cho môi trường sản xuất của một số hợp đồng ký và xác thực, bao gồm việc ký dựa trên key management system. Bạn dựa vào hợp đồng công khai trong khi phiên bản đó cung cấp bản triển khai, nhờ vậy mã của bạn vẫn có thể di chuyển giữa các phiên bản.

Xem thêm

Hợp đồng và module liên quan

Tài liệu tham khảo module Contracts — bản đồ hợp đồng được tạo đầy đủ.
Tài liệu tham khảo hợp đồng ký — SignerInterface, HsmSignerInterface, và DeferredSignerInterface.
Tài liệu tham khảo hợp đồng chính sách bảo mật — chi tiết HtmlSecurityPolicyInterface.
Tài liệu tham khảo module Event — bề mặt theo dõi vòng đời.
Quy tắc ổn định của SPI — chính sách thay đổi đứng sau mỗi thẻ @stability.
Hợp đồng nhà cung cấp KMS — hợp đồng back end ký và mô hình mối đe dọa.

Bảng thuật ngữ định nghĩa SPI, extension point, stability tag, và backward-compatibility promise; xem bảng thuật ngữ đã xuất bản để biết định nghĩa chuẩn của từng thuật ngữ.