Aturan stabilitas SPI

Sekilas

Antarmuka penyedia layanan NextPDF mengikuti Semantic Versioning. Setiap kontrak publik memiliki tag @stability dan janji kompatibilitas mundur. Gunakan aturan ini untuk menentukan kontrak mana yang aman Anda andalkan.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

Antarmuka penyedia layanan mencakup kontrak publik di namespace NextPDF\Contracts dan NextPDF\Event. Sebuah tipe hanya menjadi bagian dari antarmuka jika PHPDoc sumbernya memuat tag @stability. Tag tersebut menentukan batas kontraknya. Tipe tanpa tag bersifat internal, bahkan ketika PHP mengeksposnya sebagai public.

NextPDF mengikuti Semantic Versioning 2.0.0. Perubahan yang merusak pada kontrak stable mengharuskan kenaikan versi mayor. Kontrak baru atau penambahan yang tidak merusak menaikkan versi minor. Perbaikan bug menaikkan versi patch.

Tag @stability

Setiap kontrak mendeklarasikan salah satu dari tiga nilai stabilitas:

Tag	Makna	Aturan perubahan
stable	Siap untuk produksi. Aman untuk diandalkan.	Tidak ada perubahan yang merusak dalam rilis minor atau patch. Metode baru hanya ditambahkan dengan perilaku bawaan atau pada kontrak baru.
experimental	Dapat digunakan, tetapi belum dibekukan.	Antarmuka dapat berubah dalam rilis minor, dengan pemberitahuan penghentian terlebih dahulu.
deprecated	Dijadwalkan untuk dihapus.	Kontrak menyatakan penggantinya dan versi penghapusannya.

NextPDF mencatat setiap janji per kontrak dalam peta kontrak yang dihasilkan dan membuatnya ulang dari sumber pada setiap rilis. Teks janji tersebut memuat aturan yang tepat untuk kontrak itu. Perlakukan PHPDoc sumber kontrak sebagai satu-satunya sumber kebenaran.

Kelas janji kompatibilitas mundur

Peta kontrak mengelompokkan setiap janji ke dalam salah satu dari empat kelas:

1. Janji antarmuka. “Tidak ada perubahan yang merusak dalam rilis minor atau patch. Metode baru hanya dengan implementasi bawaan.” Berlaku untuk sebagian besar antarmuka stable, termasuk FontRegistryInterface, SignerInterface, HsmSignerInterface, dan HtmlSecurityPolicyInterface.
2. Janji enum. “Tidak ada penghapusan case. Case baru dapat ditambahkan dalam versi minor.” Berlaku untuk enum stable seperti Alignment, Orientation, dan OutputDestination.
3. Janji objek nilai beku. “Tanda tangan konstruktor dan properti publik dibekukan. Metode baru dapat ditambahkan.” Berlaku untuk objek nilai seperti TextPreprocessResult, TextSegment, dan muatan event yang terkait dengannya.
4. Janji eksperimental. “Antarmuka dapat berubah dalam versi minor dengan pemberitahuan penghentian.” Berlaku untuk kontrak experimental seperti DeferredSignerInterface, TimestampProviderInterface, CursorInterface, dan StreamingWriterInterface.

Kelas final seperti EventDispatcher atau ListenerProvider membekukan tanda tangan metode publiknya. Gunakan komposisi untuk memperluas kelas final. Jangan membuat subclass darinya.

Kontrak streaming eksperimental

CursorInterface dan StreamingWriterInterface bersifat experimental (sejak 3.1.0). NextPDF menyertakan implementasi mesin yang final dan teruji untuk kedua kontrak tersebut; kelas implementasinya bersifat internal dan bukan bagian dari permukaan publik. Gunakan perilaku streaming melalui kontrak experimental publik. Dalam sebagian besar kasus, Anda tidak mengimplementasikan kontrak itu sendiri.

Karena kontrak ini bersifat experimental, tanda tangannya dapat berubah dalam rilis minor, dengan pemberitahuan penghentian terlebih dahulu (janji eksperimental). Pin versinya secara ketat atau bungkus di balik adapter Anda sendiri sebelum mengandalkannya di produksi. Perlakukan kontrak streaming sebagai titik ekstensi yang sedang distabilkan, bukan titik yang sudah beku.

Permukaan API

Tidak ada API runtime pada halaman ini. Permukaan yang relevan adalah tag PHPDoc @stability pada setiap kontrak publik dan peta kontrak yang dibuat ulang, yang mengagregasi janji per kontrak.

Contoh kode — Mulai cepat

Baca stabilitas kontrak dari sumber sebelum Anda mengandalkannya.

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

Contoh kode — Produksi

Batasan versi Composer mengunci versi mayor; untuk kontrak stable, perubahan yang merusak terjadi di versi mayor.

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

Gunakan ^3.0 untuk menerima rilis minor dan patch tanpa perubahan yang merusak kontrak stable mana pun. Lakukan pin lebih ketat ketika Anda mengandalkan kontrak experimental, karena kontrak experimental dapat berubah dalam rilis minor.

Kasus tepi & jebakan

• Tag, bukan visibilitas. Metode PHP yang ditandai public bukan bagian dari antarmuka penyedia layanan kecuali tipe yang mendeklarasikannya memuat tag @stability.
• Pergeseran eksperimental. Kontrak experimental dapat berubah dalam rilis minor. Pin versinya secara ketat atau bungkus di balik adapter Anda sendiri. Ini berlaku untuk kontrak streaming meskipun keduanya sudah memiliki implementasi yang disertakan.
• Metode bawaan baru. Antarmuka stable dapat memperoleh metode baru yang memiliki perilaku bawaan. Implementasikan metode baru tersebut saat Anda melakukan upgrade agar implementasi Anda sendiri tetap eksplisit.
• Paritas edisi. NextPDF Pro dan NextPDF Enterprise mengikuti aturan yang sama. Kontrak yang Anda targetkan di Core tetap valid untuk implementasi Premium dari kontrak yang sama.

Siklus hidup penghentian

Sebuah kontrak melewati siklus hidup yang terdefinisi:

1. Tandai. Pemilik menetapkan @stability deprecated di PHPDoc sumber dan mencatat penggantinya serta versi penghapusannya.
2. Pemberitahuan. Penghentian diumumkan dalam changelog untuk rilis yang menandainya.
3. Tumpang tindih. Kontrak yang dihentikan dan penggantinya berdampingan setidaknya selama satu rilis minor.
4. Hapus. Kontrak dihapus dalam rilis mayor yang dinyatakan. Penghapusan tidak pernah terjadi dalam rilis minor atau patch.

Rencanakan upgrade segera setelah sebuah kontrak ditandai deprecated. Penggantinya selalu dinyatakan.

Kinerja

Halaman ini mendefinisikan kebijakan dan tidak memiliki biaya runtime.

Catatan keamanan

Kontrak penandatanganan bersifat stable dan mengikuti janji antarmuka. Metode baru pada kontrak penandatanganan hanya hadir bersama perilaku bawaan atau pada kontrak baru, sehingga implementasi berbasis perangkat keras tidak rusak saat upgrade minor. Tinjau changelog sebelum upgrade mayor, karena versi mayor dapat mengubah kontrak stable.

Konformansi

Aturan pemberian versi ini sesuai dengan Semantic Versioning 2.0.0. Pembuatan changelog mengikuti Conventional Commits 1.0.0.

Konteks komersial

NextPDF Pro dan NextPDF Enterprise mengikuti aturan stabilitas antarmuka penyedia layanan yang sama dengan Core. Kontrak yang Anda targetkan di Core tetap valid untuk implementasi Premium dari kontrak tersebut, sehingga kode ekstensi Anda portabel di seluruh edisi.

Lihat juga

• Ikhtisar penulisan ekstensi
• Fon kustom
• Pemicu tindakan dan listener event
• Kontrak penyedia KMS

Kontrak dan modul terkait

• Referensi modul kontrak — peta kontrak yang dibuat dan teks janji per kontrak.
• Referensi kontrak streaming — kontrak streaming experimental dan implementasinya yang disertakan.
• Referensi kontrak penandatanganan — kontrak penandatanganan stable dan experimental di bawah aturan yang sama.
• Ikhtisar penulisan ekstensi — makna setiap tag @stability dalam praktiknya.
• Pemicu tindakan dan listener event — dispatcher final dan muatan eksperimental yang diatur oleh aturan ini.

Glosarium mendefinisikan tag stabilitas dan janji kompatibilitas mundur. Lihat glosarium yang diterbitkan untuk definisi kanoniknya.