Pengembangan ekstensi: ikhtisar SPI publik

Sekilas pandang

NextPDF menyediakan sekumpulan kecil kontrak publik yang dirancang secara cermat di namespace NextPDF\Contracts dan NextPDF\Event. Implementasikan kontrak-kontrak ini untuk menambahkan fon, mencegat teks, mengamati siklus hidup dokumen, atau menyediakan back end penandatanganan Anda sendiri tanpa perlu melakukan fork pada mesin.

Instalasi

composer require nextpdf/core:^3

Ikhtisar konseptual

NextPDF memisahkan service provider interface (SPI) publiknya dari kode internalnya. SPI adalah kumpulan tipe yang dapat Anda implementasikan atau amati. Bagian lainnya bersifat privat dan dapat berubah tanpa pemberitahuan.

SPI publik memiliki tiga bentuk:

• Kontrak registri. Layanan yang hidup sepanjang proses dan Anda isi sebelum membuat dokumen; FontRegistryInterface dan ImageRegistryInterface adalah contoh utamanya. Daftarkan asetnya, lalu mesin akan membacanya.
• Kontrak strategi. Hook untuk satu tugas yang dipanggil oleh mesin selama render. TextPreprocessorInterface menangani pencegatan teks saat tata letak berlangsung, dan HtmlSecurityPolicyInterface mengatur akses fitur Hypertext Markup Language (HTML). Anda menyediakan perilakunya, lalu mesin memanggilnya.
• Kontrak penandatanganan. Back end kriptografi. SignerInterface, HsmSignerInterface, dan DeferredSignerInterface memungkinkan Anda menyediakan penyimpanan kunci dan produksi tanda tangan. Mesin membangun struktur Cryptographic Message Syntax (CMS), sementara kode Anda menyimpan kuncinya.

Sistem event terpisah di NextPDF\Event, yang kompatibel dengan PHP Standard Recommendation 14 (PSR-14), menangani pengamatan. Event siklus hidup memungkinkan Anda menanggapi pembuatan dokumen, halaman baru, pemuatan fon, penandatanganan, dan penulisan keluaran. Event tersebut tidak mengubah perilaku mesin.

Setiap kontrak memuat tag @stability di PHPDoc sumbernya: stable, experimental, atau deprecated. Tag tersebut, bersama jaminan kompatibilitas mundur untuk tiap kontrak, memberi tahu Anda sebesar apa perubahan yang perlu diantisipasi. Lihat Aturan stabilitas SPI untuk kebijakan selengkapnya.

Apa yang dapat diperluas

Kapabilitas	Kontrak publik	Stabilitas
Pendaftaran dan pencarian fon	NextPDF\Contracts\FontRegistryInterface	stable (sejak 1.7.0)
Caching dan dekode gambar	NextPDF\Contracts\ImageRegistryInterface	stable (sejak 2.0.0)
Pencegatan teks pada saat tata letak	NextPDF\Contracts\TextPreprocessorInterface	stable (sejak 1.9.0)
Pengaturan akses fitur HTML	NextPDF\Contracts\HtmlSecurityPolicyInterface	stable (sejak 3.1.0)
Wiring factory dokumen	NextPDF\Contracts\DocumentFactoryInterface	stable (sejak 1.7.0)
Penandatanganan sinkron	NextPDF\Contracts\SignerInterface	stable (sejak 1.0.0)
Penandatanganan berbasis perangkat keras	NextPDF\Contracts\HsmSignerInterface	stable (sejak 1.0.0)
Penandatanganan tertunda dan batch	NextPDF\Contracts\DeferredSignerInterface	experimental (sejak 3.0.0)
Pemberian stempel waktu RFC 3161	NextPDF\Contracts\TimestampProviderInterface	experimental (sejak 3.0.0)
Pengamatan siklus hidup	NextPDF\Event\* (kompatibel dengan PSR-14)	dispatcher stable; payload experimental

Apa yang BUKAN publik

Tipe-tipe berikut bersifat internal. Jangan mengimpor, membuat subclass, atau bergantung padanya:

• Kelas apa pun di luar namespace NextPDF\Contracts dan NextPDF\Event, kecuali PHPDoc-nya memuat tag @stability.
• Kode mesin konkret, termasuk parser HTML, writer, pipeline tata letak, dan font subsetter.
• Paket NextPDF Pro dan NextPDF Enterprise. Kelas internalnya bukan bagian dari permukaan open source. Jika edisi berbayar menyertakan implementasi SPI, gunakan kontrak publiknya, bukan tipe internalnya.

Permukaan API

Peta kontrak yang dihasilkan bersifat otoritatif dan dibangun ulang dari sumber pada setiap rilis. Perlakukan tag PHPDoc @stability di setiap berkas interface sebagai satu-satunya sumber kebenaran. Gunakan tabel di atas sebagai panduan membaca.

Contoh kode — Mulai cepat

Daftarkan sebuah fon, lalu pantau ketika fon tersebut dimuat. Kedua langkah ini hanya menggunakan tipe publik.

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

Contoh kode — Produksi

Pada worker yang berjalan lama, bangun registri satu kali saat boot, kunci registri tersebut, lalu injeksikan dispatcher bersama melalui factory dokumen.

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

Kasus tepi & jebakan

• Penguncian registri. Setelah FontRegistryInterface::lock(), metode pengubah akan melempar LogicException. Kunci hanya setelah warmup selesai.
• Ketidaksesuaian stabilitas. Kontrak experimental dapat berubah pada rilis minor. Periksa stabilitas yang tercantum sebelum Anda bergantung pada kontrak tersebut di produksi.
• Disiplin namespace. Tipe di luar NextPDF\Contracts atau NextPDF\Event yang tidak memiliki tag @stability bersifat internal, meskipun secara teknis ditandai public.

Performa

SPI tidak menimbulkan overhead saat tidak digunakan. Jika tidak ada listener yang terikat pada suatu kelas event, dispatcher event langsung kembali setelah satu kali pemeriksaan hasListeners(). Registri menyimpan data PHP murni dan mendukung warmup saat boot untuk mengurangi latensi permintaan pertama.

Catatan keamanan

Kontrak penandatanganan adalah permukaan yang sensitif dari sisi keamanan. HsmSignerInterface mengharuskan kunci privat tidak pernah keluar dari batas perangkat keras. Implementasi Anda harus memenuhi persyaratan tersebut. Lihat kontrak penyedia key management system (KMS) untuk kontrak back end penandatanganan pihak ketiga beserta model ancamannya.

Kesesuaian

Tidak ada klaim normatif yang dibuat pada halaman ikhtisar ini. Kesesuaian tiap kontrak, termasuk PDF Advanced Electronic Signatures (PAdES) dan manajemen kunci, didokumentasikan di halaman SPI yang relevan.

Konteks komersial

NextPDF Pro dan NextPDF Enterprise menyediakan implementasi produksi untuk beberapa kontrak penandatanganan dan validasi, termasuk penandatanganan berbasis key management system. Kode Anda bergantung pada kontrak publik, sementara edisi tersebut menyediakan implementasinya, sehingga kode Anda tetap portabel antaredisi.

Lihat juga

• Aturan stabilitas SPI
• Fon kustom
• Tata letak kustom dan pencegatan teks
• Pemicu aksi dan listener event
• Kontrak penyedia KMS

Kontrak dan modul terkait

• Referensi modul Contracts — peta kontrak lengkap yang dihasilkan.
• Referensi kontrak penandatanganan — SignerInterface, HsmSignerInterface, dan DeferredSignerInterface.
• Referensi kontrak kebijakan keamanan — rincian HtmlSecurityPolicyInterface.
• Referensi modul Event — permukaan pengamatan siklus hidup.
• Aturan stabilitas SPI — kebijakan perubahan di balik setiap tag @stability.
• Kontrak penyedia KMS — kontrak back end penandatanganan dan model ancamannya.

Glosarium mendefinisikan SPI, extension point, stability tag, dan backward-compatibility promise; lihat glosarium yang diterbitkan untuk definisi kanonik masing-masing.