Quy tắc ổn định SPI

Tổng quan nhanh

Service provider interface của NextPDF tuân theo Semantic Versioning. Mỗi hợp đồng công khai đều có một thẻ @stability và một cam kết tương thích ngược. Hãy dùng các quy tắc này để quyết định bạn có thể dựa vào hợp đồng nào.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Service provider interface gồm các hợp đồng công khai trong namespace NextPDF\Contracts và NextPDF\Event. Một kiểu chỉ thuộc interface khi PHPDoc nguồn của nó có thẻ @stability. Thẻ này xác định ranh giới. Một kiểu không có thẻ này là nội bộ, ngay cả khi PHP hiển thị nó dưới dạng public.

NextPDF tuân theo Semantic Versioning 2.0.0. Một thay đổi gây phá vỡ đối với hợp đồng stable phải tăng phiên bản lớn (major). Một hợp đồng mới hoặc một phần bổ sung không gây phá vỡ sẽ làm tăng phiên bản nhỏ (minor). Một bản sửa lỗi sẽ làm tăng phiên bản vá (patch).

Thẻ @stability

Mỗi hợp đồng khai báo một trong ba giá trị độ ổn định:

Thẻ	Ý nghĩa	Quy tắc thay đổi
`stable`	Sẵn sàng cho môi trường production. Có thể dựa vào an toàn.	Không có thay đổi gây phá vỡ trong một bản phát hành nhỏ (minor) hoặc bản vá (patch). Phương thức mới chỉ được thêm khi có hành vi mặc định đi kèm hoặc trong một hợp đồng mới.
`experimental`	Có thể dùng, nhưng chưa được cố định.	Interface có thể thay đổi trong một bản phát hành nhỏ (minor), kèm thông báo loại bỏ trước.
`deprecated`	Đã được lên lịch loại bỏ.	Hợp đồng nêu rõ phương án thay thế và phiên bản loại bỏ.

NextPDF ghi lại cam kết của từng hợp đồng trong bản đồ hợp đồng được tạo ra và tái tạo bản đồ đó từ mã nguồn ở mỗi bản phát hành. Nội dung cam kết nêu chính xác quy tắc cho hợp đồng đó. Hãy coi PHPDoc nguồn của hợp đồng là nguồn thông tin duy nhất đáng tin cậy.

Các lớp cam kết tương thích ngược

Bản đồ hợp đồng ghi lại từng cam kết theo một trong bốn lớp:

Cam kết interface. “Không có thay đổi gây phá vỡ trong một bản phát hành nhỏ (minor) hoặc bản vá (patch). Phương thức mới chỉ được thêm khi có triển khai mặc định.” Áp dụng cho hầu hết các interface stable, bao gồm FontRegistryInterface, SignerInterface, HsmSignerInterface và HtmlSecurityPolicyInterface.
Cam kết enum. “Không loại bỏ case nào. Có thể thêm case mới trong một phiên bản nhỏ (minor).” Áp dụng cho các enum stable như Alignment, Orientation và OutputDestination.
Cam kết value object đã được cố định. “Chữ ký constructor và các thuộc tính public được cố định. Có thể thêm phương thức mới.” Áp dụng cho các value object như TextPreprocessResult, TextSegment và các event payload gắn với nó.
Cam kết experimental. “Interface có thể thay đổi trong một phiên bản nhỏ (minor) kèm thông báo loại bỏ.” Áp dụng cho các hợp đồng experimental như DeferredSignerInterface, TimestampProviderInterface, CursorInterface và StreamingWriterInterface.

Một lớp final như EventDispatcher hay ListenerProvider cố định chữ ký của các phương thức public. Hãy dùng composition để mở rộng một lớp final. Đừng tạo lớp con từ lớp đó.

Các hợp đồng streaming experimental

CursorInterface và StreamingWriterInterface là experimental (kể từ 3.1.0). NextPDF cung cấp các triển khai engine final đã được kiểm thử cho cả hai hợp đồng; các lớp triển khai là nội bộ và không thuộc bề mặt công khai. Bạn sử dụng hành vi streaming thông qua hợp đồng experimental công khai. Trong hầu hết các trường hợp, bạn không tự triển khai các hợp đồng này.

Vì hợp đồng streaming là experimental, chữ ký của nó có thể thay đổi trong một bản phát hành nhỏ (minor), kèm thông báo loại bỏ trước (cam kết experimental). Hãy ghim chặt phiên bản hoặc bọc nó sau adapter của riêng bạn trước khi dựa vào nó trong môi trường production. Hãy coi hợp đồng streaming là một điểm mở rộng đang dần ổn định, không phải một điểm đã được cố định.

Bề mặt API

Trang này không có giao diện lập trình ứng dụng (API) lúc chạy. Bề mặt liên quan là thẻ PHPDoc @stability trên mọi hợp đồng công khai và bản đồ hợp đồng được tạo lại để tổng hợp cam kết của từng hợp đồng.

Mẫu code — bắt đầu nhanh

Hãy đọc độ ổn định của một hợp đồng từ mã nguồn trước khi bạn dựa vào nó.

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

Mẫu code — production

Ràng buộc phiên bản Composer sẽ ghim phiên bản lớn (major), là nơi có thể xảy ra các thay đổi gây phá vỡ đối với một hợp đồng stable.

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

Hãy dùng ^3.0 để nhận các bản phát hành nhỏ (minor) và bản vá (patch) mà không có thay đổi gây phá vỡ nào đối với bất kỳ hợp đồng stable nào. Hãy ghim chặt hơn khi bạn dựa vào hợp đồng experimental, vì hợp đồng experimental có thể thay đổi trong một bản phát hành nhỏ (minor).

Trường hợp đặc biệt và lưu ý

Thẻ, không phải mức truy cập. Một phương thức PHP được đánh dấu public không thuộc service provider interface trừ khi kiểu khai báo nó có thẻ @stability.
Thay đổi ở experimental. Một hợp đồng experimental có thể thay đổi trong một bản phát hành nhỏ (minor). Hãy ghim chặt phiên bản hoặc bọc nó sau adapter của riêng bạn. Điều này áp dụng cho các hợp đồng streaming ngay cả khi chúng đã có các triển khai được cung cấp sẵn.
Phương thức mặc định mới. Một interface stable có thể được bổ sung một phương thức có hành vi mặc định. Hãy triển khai phương thức mới khi bạn nâng cấp để triển khai của riêng bạn vẫn tường minh.
Tương đương giữa các phiên bản sản phẩm. NextPDF Pro và NextPDF Enterprise tuân theo cùng các quy tắc. Một hợp đồng bạn nhắm tới trong Core vẫn hợp lệ đối với triển khai Premium của cùng hợp đồng đó.

Vòng đời loại bỏ

Một hợp đồng trải qua vòng đời được xác định:

Đánh dấu. Chủ sở hữu đặt @stability deprecated trong PHPDoc nguồn và ghi lại phương án thay thế cùng phiên bản loại bỏ.
Thông báo. Việc loại bỏ được công bố trong changelog của bản phát hành đánh dấu nó.
Giai đoạn song hành. Hợp đồng đã được đánh dấu loại bỏ và phương án thay thế của nó cùng tồn tại trong ít nhất một bản phát hành nhỏ (minor).
Loại bỏ. Hợp đồng được loại bỏ trong bản phát hành lớn (major) đã nêu. Việc loại bỏ không bao giờ xảy ra trong một bản phát hành nhỏ (minor) hoặc bản vá (patch).

Hãy lên kế hoạch nâng cấp ngay khi một hợp đồng được đánh dấu deprecated. Luôn có phương án thay thế được nêu rõ.

Hiệu năng

Trang này định nghĩa chính sách. Trang không phát sinh chi phí lúc chạy.

Ghi chú bảo mật

Các hợp đồng ký là stable và tuân theo cam kết interface. Một phương thức mới trên hợp đồng ký chỉ xuất hiện khi có hành vi mặc định đi kèm hoặc trong một hợp đồng mới, nên triển khai dựa trên phần cứng sẽ không bị hỏng khi nâng cấp nhỏ (minor). Hãy xem changelog trước khi nâng cấp lớn (major), vì một phiên bản lớn (major) có thể thay đổi hợp đồng stable.

Sự tuân thủ

Các quy tắc đánh phiên bản này tuân thủ Semantic Versioning 2.0.0. Việc tạo changelog tuân theo Conventional Commits 1.0.0.

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

NextPDF Pro và NextPDF Enterprise tuân theo cùng các quy tắc ổn định của service provider interface như Core. Một hợp đồng bạn nhắm tới trong Core vẫn hợp lệ đối với triển khai Premium của hợp đồng đó, nên code mở rộng của bạn có thể dùng xuyên suốt các phiên bản sản phẩm.

Xem thêm

Các 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 ra và cam kết của từng hợp đồng.
Tài liệu tham khảo về các hợp đồng streaming — các hợp đồng streaming experimental và các triển khai được cung cấp sẵn.
Tài liệu tham khảo về các hợp đồng ký — các hợp đồng ký stable và experimental theo cùng những quy tắc này.
Tổng quan về việc viết phần mở rộng — mỗi thẻ @stability nghĩa là gì trong thực tế.
Trình kích hoạt hành động và trình lắng nghe sự kiện — dispatcher final và các payload experimental do những quy tắc này chi phối.

Bảng thuật ngữ định nghĩa thẻ độ ổn định và cam kết tương thích ngược. Hãy xem bảng thuật ngữ đã xuất bản để biết các định nghĩa chuẩn.