Pro edycja

Kod kreskowy

W skrócie

NextPDF Pro dodaje specjalistyczne symboliki kodów kreskowych 2D i łańcucha dostaw ponad symboliki liniowe i QR z edycji open source. Każda symbolika renderuje się bezpośrednio na powierzchni strony PDF jako deterministyczny strumień zawartości.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/pro:^3

Enkodery Pro rejestrują się same przez standardowy rejestr enkoderów kodów kreskowych. Aplikacje, które budują własny rejestr, mogą jawnie ponownie zarejestrować enkodery Pro przez opublikowanego dostawcę usług.

Przegląd koncepcyjny

Edycja open source obejmuje codzienne symboliki liniowe i QR. NextPDF Pro rozszerza ten sam rejestr o specjalistyczne symboliki na potrzeby handlu detalicznego, logistyki, usług pocztowych oraz zastosowań przemysłowych o wysokiej gęstości:

Micro QR Code — kompaktowy wariant QR dla małej powierzchni etykiety.
DotCode — symbolika typu matrycy punktowej zaprojektowana do szybkiego znakowania przemysłowego.
Han Xin Code — symbolika 2D z natywną pojemnością dla dużego zestawu znaków tekstu CJK, zgodnie z ISO/IEC 20830.
JabCode — wielobarwna symbolika 2D z kaskadowaniem wielu symboli.
rMQR — prostokątny wariant Micro QR dla wąskich, szerokich etykiet.
GS1 DataBar — rodzina symbolik handlowych i kuponowych GS1.
GS1 Composite (CC-C) — powiązana baza 1D wraz z wysokogęstościowym komponentem rozszerzającym 2D PDF417, niosącym dane GS1 Application Identifier. (Kodowanie komponentów rozszerzających 2D CC-A i CC-B nie jest obsługiwane w tym wydaniu; zobacz macierz obsługi.)

Każdy enkoder wytwarza obiekt danych kodu kreskowego, który renderer strony przekształca na operatory zawartości PDF. Kodowanie jest deterministyczne: to samo wejście i te same opcje zawsze dają ten sam wzorzec modułów, dzięki czemu podpisane i zarchiwizowane dokumenty pozostają odtwarzalne.

Szczegółowa dokumentacja kodów kreskowych zawiera macierz obsługi dla każdej symboliki wraz z dowodami. Dla każdej symboliki i wariantu macierz zapisuje jeden z trzech stanów: ćwiczy je wewnątrzrepozytoryjna oprawa konformancji (Verified), powierzchnia implementacji potwierdza je bez dedykowanej oprawy (Claimed) albo wypadają poza zakres (Not supported). NextPDF raportuje macierz uczciwie: wariant, który dostarcza enkoder, lecz nie ma oprawy śledzącej odniesienie, pozostaje oznaczony jako Claimed z notatką o uzupełnieniu, zamiast być zawyżony.

Dlaczego działa to w ten sposób

Każdy enkoder Pro jest funkcją czystą: ten sam ładunek i te same opcje zawsze dają tę samą macierz modułów, bez ukrytego stanu ani zasianej losowości. Ten determinizm to decyzja nośna. Pozwala kodowi kreskowemu przejść tam i z powrotem przez podpisany lub zarchiwizowany dokument bez zaburzania strumienia bajtów, dzięki czemu ponowne renderowanie nigdy nie unieważnia podpisu. Czyni też konformancję audytowalną: macierz obsługi przypina każdą symbolikę do zapisanego śladu odniesienia, sprawdzanego bit po bicie względem pliku wzorcowego. Rozszerzenie BarcodeEncoderRegistry z Core zamiast jego rozgałęzienia utrzymuje te gwarancje identycznymi w edycji open oraz Pro.

Tło projektowe: Te same bajty za każdym razem: odtwarzalne pliki PDF.

Powierzchnia API

composer require nextpdf/pro:^3

Publiczna powierzchnia kodów kreskowych Pro składa się z:

Statycznego punktu wejścia dostawcy usług, który rejestruje enkodery 2D Pro w rejestrze enkoderów kodów kreskowych (MicroQR, DotCode, HanXin, JabCode, RMQR, GS1DataBar oraz klucz komponentu GS1 Composite CC-C gs1-composite-cc-c). Kodowanie komponentów rozszerzających 2D GS1 Composite CC-A i CC-B nie jest obsługiwane w tym wydaniu i nie jest rejestrowane.
Parsera GS1 Application Identifier, który przyjmuje zarówno czytelne dla człowieka ciągi AI, jak i identyfikatory URI GS1 Digital Link, i wytwarza zakodowane sekwencje bajtów dla nośników GS1-128, QR Code oraz Data Matrix.
Walidatora łańcucha dostaw GS1, który sprawdza cyfry kontrolne, strukturę AI, logikę dat oraz obowiązkowe kombinacje AI wynikające z profilu branżowego.

Pełna wygenerowana tabela sygnatur metod renderuje się w szczegółowej dokumentacji kodów kreskowych.

Przykład kodu — Szybki start

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

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

Przykład kodu — Produkcja

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,
        ]);
    }
}

Przypadki brzegowe i pułapki

Domyślny rejestr wstępnie wiąże wpisy enkoderów Pro leniwie i bramkuje je przez rejestr możliwości. Jawne wywołanie BarcodeProServiceProvider::register() to obsługiwane rozwiązanie awaryjne, gdy aplikacja komponuje własny rejestr bez domyślnych wpisów.
Ponowna rejestracja jest idempotentna: drugie wywołanie register() zastępuje pierwsze wiązanie, zamiast zgłaszać wyjątek.
Pokrycie wariantów GS1 DataBar jest celowo częściowe. Omnidirectional, Truncated, Stacked, Stacked Omnidirectional oraz Limited są zweryfikowane referencyjnie; Expanded i Expanded Stacked są poza zakresem w tym wydaniu. Zobacz macierz obsługi.
rMQR przyjmuje każdą wersję ISO 23941 przez pakiet konformancji zwalidowany według załącznika. Metadane śledzenia zakresu, które poprzedzają późniejsze rozszerzenie zakresu rozmiarów, mogą to zaniżać; macierz obsługi zapisuje rzeczywistość zweryfikowaną na poziomie kodu.

Wydajność

Koszt kodowania skaluje się z długością ładunku i docelowym rozmiarem symbolu. Każda symbolika rozkłada swój symbol w jednym przebiegu, bez ponownego przepływu. Kaskady wielu symboli JabCode skalują się z liczbą symboli (1–61). Kodowanie utrzymuje macierz modułów w pamięci; koszt ogranicza największa wybrana wersja symbolu.

Uwagi dotyczące bezpieczeństwa

Enkodery kodów kreskowych nie wykonują treści ładunku; kodują ją jako dane. Walidacja GS1 odrzuca zniekształcone struktury AI i nieprawidłowe cyfry kontrolne przed kodowaniem, co zapobiega temu, by zniekształcony ciąg łańcucha dostaw wytworzył skanowalny, lecz niekonformantny symbol. Same enkodery nie logują żadnego ładunku; aplikacje muszą oczyścić wrażliwe ładunki z własnych logów.

Konformancja

Każda symbolika podąża za właściwym opublikowanym standardem (ISO/IEC 24724 dla GS1 DataBar, ISO/IEC 24723 dla GS1 Composite, ISO/IEC 23941 dla rMQR, ISO/IEC 18004 Annex dla Micro QR, ISO/IEC 20830 dla Han Xin Code, ISO/IEC 23634 dla JabCode, USPS-B-3200 dla symboliki pocztowej). Mapowanie konformancji na poziomie klauzul z identyfikatorami cytowań renderuje się w szczegółowej dokumentacji kodów kreskowych.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.