Tạo mã vạch GS1 Composite (sóng mang CC-C)

Tổng quan nhanh

Năng lực xem trước opt-in — mặc định TẮT. Hỗ trợ GS1 Composite là một tính năng thử nghiệm, opt-in. Composite duy nhất đã xuất xưởng là CC-C (sóng mang PDF417 đầy đủ): Core đăng ký năng lực barcode.gs1-composite-cc-c và gói Premium (nextpdf/pro) kiểm soát bộ mã hóa đằng sau nó. Chỉ với Core, năng lực được đăng ký nhưng trạng thái của nó là Unavailable, nên không có gì được phát ra. CC-A và CC-B chưa khả dụng: một yêu cầu mã hóa một trong hai sẽ fail closed với một ngoại lệ có kiểu (UnsupportedBarcodeFeature). Đây là một ranh giới phạm vi đã ghi tài liệu, không phải một lỗi.

Một biểu tượng GS1 Composite ghép một thành phần tuyến tính (định danh mặt hàng chính) với một thành phần composite 2D (dữ liệu mở rộng như lô hàng hay hạn dùng). Công thức này cho thấy cách năng lực composite được đăng ký và phân giải, Core cung cấp gì, Premium thêm gì, và chính xác chỗ hỗ trợ dừng lại.

Cài đặt

composer require nextpdf/core:^3

Bộ mã hóa composite CC-C cần gói Premium:

composer require nextpdf/pro

Tổng quan khái niệm

NextPDF phân giải một symbology qua registry năng lực, theo cùng cách mô-đun Barcode phân giải bất kỳ bộ mã hóa nào. Một năng lực GS1 Composite được đăng ký ở đó:

• barcode.gs1-composite-cc-c được đăng ký trong CapabilityRegistry ở Core, dưới tầng sản phẩm Pro. Đó là sóng mang PDF417 đầy đủ (ISO/IEC 15438) cho thành phần composite CC-C. Bộ mã hóa Pro định tuyến payload qua bộ mã hóa PDF417 core chuẩn. Năng lực luôn được đăng ký nhưng chỉ Available khi Premium được cài — chỉ với Core thì trạng thái của nó là Unavailable, nên nó được đăng ký nhưng vô hiệu (opt-in, mặc định TẮT).

Không có năng lực CC-A hay CC-B nào được đăng ký. Một thành phần 2D CC-A/CC-B đúng chuẩn cần high-level encodation base-928 theo ISO/IEC 24723 Clause 5 cộng với một sóng mang riêng cho thành phần, và bản phát hành này không triển khai đường đó, nên việc quảng bá một năng lực CC-A/CC-B sẽ đặt tên cho một bộ mã hóa không thể phát ra một biểu tượng giải mã được.

Ranh giới fail-closed — cái gì chưa khả dụng

CC-A và CC-B được chủ ý không xuất xưởng dưới dạng các symbology dùng được:

• CC-A — một nguyên thủy radix base-928 mức thấp (Base928Converter, chỉ codeword) và một bộ dựng chuỗi nhị phân Clause-5 tồn tại nội bộ, nhưng high-level encodation CC-A đầy đủ theo ISO/IEC 24723 Clause 5 và sóng mang riêng cho CC-A chưa được triển khai, nên không có biểu tượng CC-A dùng được nào được tạo ra. CompositeComponentA::encode() luôn ném ngoại lệ có kiểu UnsupportedBarcodeFeature.
• CC-B — thành phần composite dung lượng trung bình cũng tương tự chưa được triển khai; CompositeComponentB::encode() luôn ném UnsupportedBarcodeFeature.

Các thành phần này fail closed: một yêu cầu mã hóa một trong hai làm phát sinh một ngoại lệ có kiểu thay vì phát ra một biểu tượng một phần hay sai. Đây là một đường phạm vi có chủ ý, không phải một lỗi.

Đường CC-C đã xuất xưởng tuân theo một kỷ luật codeword-golden: các codeword nó tạo ra được ghim đối chiếu với một golden và kiểm tra chéo bằng một bộ giải mã độc lập, nên một dòng codeword CC-C được kiểm chứng, không chỉ được tạo ra. Không có tuyên bố chứng nhận đầu-cuối nào đối với tiêu chuẩn GS1 Composite.

Bề mặt API

Các biểu tượng GS1 Composite phân giải qua registry năng lực chứ không qua một phương thức façade cấp cao mới:

• NextPDF\Support\CapabilityRegistry — phép tra cứu báo cáo liệu barcode.gs1-composite-cc-c có Available trong phiên bản hiện tại hay không. Dùng get('barcode.gs1-composite-cc-c')->status cho quyết định khả dụng; has() chỉ báo rằng năng lực đã được đăng ký (đúng kể cả trên các bản cài chỉ-Core), nên nó không phải cổng khả dụng.
• Bộ mã hóa composite CC-C do nextpdf/pro cung cấp và được đăng ký đằng sau cùng hợp đồng bộ mã hóa mà trang Contracts / Barcode ghi tài liệu.
• Không có bộ mã hóa CC-A hay CC-B nào để gọi. Các lớp thành phần CC-A/CC-B fail closed trên encode().

Chạy composer docs:generate-api-php -- --module=Barcode để có bảng bộ mã hóa được tạo.

Mẫu mã — Khởi đầu nhanh

Kiểm tra rằng năng lực sóng mang CC-C khả dụng trước khi bạn phụ thuộc vào nó. Chỉ với Core nó được đăng ký nhưng Unavailable; với Premium được cài nó Available. Hãy kiểm soát theo trạng thái, không theo has() — has() đúng cả trên một bản cài chỉ-Core, vì năng lực luôn được đăng ký.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Support\CapabilityRegistry;
use NextPDF\Support\CapabilityStatus;

$registry = CapabilityRegistry::getInstance();

$capability = $registry->get('barcode.gs1-composite-cc-c');

if ($capability->status === CapabilityStatus::Available) {
    echo "CC-C composite carrier is available (Premium present)\n";
} else {
    echo "CC-C composite carrier needs nextpdf/pro\n";
}

Mẫu mã — Sản phẩm

Hãy kiểm soát theo trạng thái năng lực, và xử lý các thành phần không khả dụng một cách tường minh. Một biểu tượng CC-C trung thực hoặc một lần từ chối rõ ràng — không bao giờ là một composite sai.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Support\CapabilityRegistry;
use NextPDF\Support\CapabilityStatus;

final readonly class CompositeLabelService
{
    public function __construct(private CapabilityRegistry $registry) {}

    /**
     * Assert that the only shipped GS1 Composite (CC-C) is available before use.
     *
     * The capability is opt-in and default-OFF: on a Core-only install it is
     * registered but its status is Unavailable, so check the status — not has().
     */
    public function assertCompositeAvailable(): void
    {
        $status = $this->registry->get('barcode.gs1-composite-cc-c')->status;

        if ($status !== CapabilityStatus::Available) {
            // Core-only install. The CC-C encoder needs Premium. Fail fast with
            // a clear upgrade message rather than emitting a degraded symbol.
            throw new \RuntimeException(
                'GS1 Composite CC-C requires nextpdf/pro.',
            );
        }
    }

    // CC-A and CC-B are NOT yet available. Their component classes fail closed:
    // calling encode() always throws NextPDF\Pro\Barcode\Gs1Composite\
    // UnsupportedBarcodeFeature. There is no runnable CC-A/CC-B encode path —
    // CC-C is the only shipped GS1 Composite symbology. Do not call encode() on
    // CC-A/CC-B expecting a symbol.
    public function note(): string
    {
        return 'CC-A and CC-B are not available; use CC-C.';
    }
}

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

• CC-C cần Premium để khả dụng, và nó mặc định TẮT. Core đăng ký năng lực dưới tầng Pro; bộ mã hóa đằng sau nó đi kèm trong nextpdf/pro. Trên một bản cài chỉ-Core năng lực được đăng ký nhưng trạng thái của nó là Unavailable. Hãy kiểm soát theo get(...)->status, không theo has() — has() đúng cả trên chỉ-Core vì mục này luôn được đăng ký.
• Không có bộ mã hóa CC-A dùng được. Một nguyên thủy radix base-928 mức thấp tồn tại nội bộ, nhưng high-level encodation CC-A đầy đủ theo ISO/IEC 24723 Clause 5 và sóng mang riêng cho CC-A chưa được triển khai, nên không có biểu tượng CC-A nào được tạo ra.
• CC-A và CC-B fail closed. encode() của chúng luôn ném ngoại lệ có kiểu UnsupportedBarcodeFeature thay vì phát ra một biểu tượng một phần. Đây là một ranh giới phạm vi đã ghi tài liệu, có chủ ý.
• Các định danh ứng dụng GS1 vẫn áp dụng. Thành phần tuyến tính mang dữ liệu có cấu trúc GS1 với tiền tố FNC1, như trong Tạo mã vạch 1D và 2D.
• Giới hạn payload. Một payload composite lớn hơn cho ra một biểu tượng dày đặc hơn. Hãy giới hạn độ dài payload trước khi mã hóa.

Hiệu năng

Việc tạo codeword tuyến tính theo độ dài payload; việc phát sóng mang tuyến tính theo diện tích ma trận. Không có bước rasterize — mỗi module là một toán tử đường — nên bộ nhớ vẫn phẳng bất kể kích thước biểu tượng. Công thức nằm trong ngân sách 1500 ms / 64 MB.

Ghi chú bảo mật

Một biểu tượng composite mang bất kỳ payload nào bạn truyền; hãy coi giá trị đó là không tin cậy ở phía tiêu thụ. Các bộ mã hóa mã hóa byte và không xác thực chúng. Hãy giới hạn độ dài payload trước khi mã hóa để giữ kích thước biểu tượng và khối lượng công việc trong ngân sách.

Sự tuân thủ

Tuyên bố	Tiêu chuẩn	Điều khoản
Thành phần composite CC-C đã xuất xưởng dùng một sóng mang PDF417.	ISO/IEC 15438 (PDF417)	§5
High-level encodation base-928 của CC-A là phương pháp Clause 5 mà bản phát hành này không triển khai.	ISO/IEC 24723 (GS1 Composite)	§5

Đây là một bản triển khai xem trước thử nghiệm, opt-in. Core đăng ký năng lực barcode.gs1-composite-cc-c dưới tầng Pro; gói Premium kiểm soát bộ mã hóa CC-C, vốn mặc định TẮT trên một bản cài chỉ-Core (trạng thái Unavailable). CC-A và CC-B chưa khả dụng — encode() của chúng fail closed với ngoại lệ có kiểu UnsupportedBarcodeFeature. Các codeword CC-C đã xuất xưởng được ghim đối chiếu với một golden và kiểm tra chéo bằng một bộ giải mã độc lập. Không có tuyên bố GA, tuân thủ, hay chứng nhận đầu-cuối nào đối với tiêu chuẩn GS1 Composite, và không có văn bản tiêu chuẩn nào được tái tạo.

Xem thêm

• Mô-đun Barcode
• Tạo mã vạch 1D và 2D
• Contracts / Barcode