Pro 版本

條碼

速覽

NextPDF Pro 在開源版本的線性與 QR 符號系統之上，新增特殊 2D 與供應鏈條碼符號系統。每個符號系統都會作為一個確定性的內容串流，直接呈現到一個 PDF 頁面表面上。

可用性與授權

此能力隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 層級授權封套啟用。缺少該權利的部署不會載入此能力的類別。比較各版本並取得授權。

安裝

composer require nextpdf/pro:^3

Pro 編碼器會透過標準的條碼編碼器登錄自行登錄。建構自有登錄的應用程式，可透過已發布的服務供應者明確地重新登錄這些 Pro 編碼器。

概念總覽

開源版本涵蓋日常的線性與 QR 符號系統。NextPDF Pro 以特殊符號系統擴充同一個登錄，供零售、物流、郵政與高密度工業用途使用：

Micro QR Code — 適用於狹小標籤空間的精簡 QR 變體。
DotCode — 一種為高速工業標記而設計的點陣符號系統。
Han Xin Code — 一種具備原生大字集 CJK 文字容量的 2D 符號系統，依 ISO/IEC 20830。
JabCode — 一種帶有多符號串接的多彩 2D 符號系統。
rMQR — 適用於狹窄、寬幅標籤的矩形 Micro QR 變體。
GS1 DataBar — GS1 零售與優惠券符號系統家族。
GS1 Composite (CC-C) — 一個連結的 1D 基底加上一個高密度 PDF417 2D 擴充元件，承載 GS1 Application Identifier 資料。（本版本不支援 CC-A 與 CC-B 2D 擴充元件編碼；請參閱支援矩陣。）

每個編碼器會產生一個條碼資料物件，由頁面呈現器將其轉換為 PDF 內容運算子。編碼是確定性的：相同的輸入與選項一律產生相同的模組圖樣，這讓已簽署與已封存的文件得以重現。

條碼深入參考帶有一個逐符號系統、附帶佐證的支援矩陣。對於每個符號系統與變體，矩陣會記錄三種狀態之一：有一個儲存庫內的一致性 fixture 演練它（Verified）、實作介面斷言它但沒有專用的 fixture（Claimed），或它落在範圍之外（Not supported）。NextPDF 誠實地回報這個矩陣：一個隨附編碼器但缺少參考軌跡 fixture 的變體會維持 Claimed 並附上回填註記，而非誇大其詞。

為何以此方式運作

每個 Pro 編碼器都是純函式：相同的酬載與選項一律產生相同的模組矩陣，沒有隱藏狀態或帶種子的隨機性。這份確定性是承載全局的決定。它讓條碼能往返穿過已簽署或已封存的文件而不擾動位元組串流，因此重新呈現絕不會使簽章失效。它也讓一致性可稽核：支援矩陣將每個符號系統釘定到一份儲存的參考軌跡，逐位元對照黃金檔案檢查。擴充 Core 的 BarcodeEncoderRegistry 而非分叉它，讓這些保證在開源版本與 Pro 版本間維持一致。

設計背景：每次都是相同位元組：可重現的 PDF。

API 介面

composer require nextpdf/pro:^3

Pro 條碼公開介面由以下組成：

一個靜態服務供應者進入點，它將 Pro 2D 編碼器登錄到一個條碼編碼器登錄中（MicroQR、DotCode、HanXin、JabCode、RMQR、GS1DataBar，以及 GS1 Composite CC-C 元件鍵 gs1-composite-cc-c）。本版本不支援 GS1 Composite CC-A 與 CC-B 2D 擴充元件編碼，且不會登錄。
一個 GS1 Application Identifier 剖析器，它接受人類可讀的 AI 字串與 GS1 Digital Link URI 兩者，並為 GS1-128、QR Code 與 Data Matrix 載體產生編碼後的位元組序列。
一個 GS1 供應鏈驗證器，它檢查檢查碼、AI 結構、日期邏輯，以及產業設定檔的必填 AI 組合。

完整產生的方法簽章表呈現於條碼深入參考。

程式碼範例 — 快速上手

use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Pro\Barcode\BarcodeProServiceProvider;

$registry = new BarcodeEncoderRegistry();
BarcodeProServiceProvider::register($registry);
// $registry now resolves the Pro specialty symbologies.

程式碼範例 — 正式環境

use NextPDF\Pro\Barcode\Gs1\Gs1Validator;
use NextPDF\Pro\Barcode\Gs1\Gs1SupplyChainProfile;

$result = Gs1Validator::validate(
    '(01)09521234543213(17)260131(10)ABC123',
    Gs1SupplyChainProfile::NONE,
);

if (! $result->isValid) {
    // Surface findings to your observability pipeline before encoding.
    foreach ($result->findings as $finding) {
        $logger->warning('GS1 validation finding', [
            'rule' => $finding->ruleId,
            'detail' => $finding->message,
        ]);
    }
}

邊界案例與陷阱

預設登錄會惰性地預先繫結 Pro 編碼器項目，並透過能力登錄閘控它們。當一個應用程式組成自己且無預設的登錄時，明確呼叫 BarcodeProServiceProvider::register() 是受支援的回退做法。
重新登錄是冪等的：第二次 register() 呼叫會取代第一次的繫結，而非擲出錯誤。
GS1 DataBar 變體涵蓋在設計上為部分。Omnidirectional、Truncated、Stacked、Stacked Omnidirectional 與 Limited 經參考驗證；Expanded 與 Expanded Stacked 在本版本中不在範圍內。請參閱支援矩陣。
rMQR 透過經 Annex 驗證的一致性套件接受每一個 ISO 23941 版本。早於後續尺寸範圍擴充的範圍追蹤中繼資料可能低估這點；支援矩陣記錄了經程式碼驗證的實際情況。

效能

編碼成本隨酬載長度與目標符號大小而擴展。每個符號系統都在單一遍歷中布置其符號，無需 reflow。JabCode 多符號串接隨符號數量（1–61）而擴展。編碼會將模組矩陣保留在記憶體中；所選的最大符號版本為成本設下界限。

安全注意事項

條碼編碼器不執行酬載內容；它們將其編碼為資料。GS1 驗證會在編碼之前拒絕格式錯誤的 AI 結構與無效的檢查碼，這可防止一個格式錯誤的供應鏈字串產生一個可掃描但不一致的符號。編碼器本身不記錄任何酬載；應用程式必須從其自有日誌中清洗敏感酬載。

一致性

每個符號系統遵循其相關的已發布標準（GS1 DataBar 為 ISO/IEC 24724、GS1 Composite 為 ISO/IEC 24723、rMQR 為 ISO/IEC 23941、Micro QR 為 ISO/IEC 18004 Annex、Han Xin Code 為 ISO/IEC 20830、JabCode 為 ISO/IEC 23634、郵政符號系統為 USPS-B-3200）。帶有引用識別碼的條款層級一致性對應呈現於條碼深入參考。

發布邊界

本頁僅記錄外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名與工單前綴皆不在範圍內。