Contracts / Barcode

W skrócie

Obszar kodów kreskowych definiuje cztery kontrakty: koder jednowymiarowy (1D), koder dwuwymiarowy (2D), ogólny koder wykrywany przez rejestr oraz parser danych GS1. Razem określają interfejs, który muszą spełniać usługi kodów kreskowych. Implementacje symbolik są rejestrowane dla tych kontraktów.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Koder kodu kreskowego zamienia łańcuch z ładunkiem w macierz modułów, którą rysuje moduł zapisujący PDF (Portable Document Format). NextPDF dzieli kontrakty koderów według wymiarowości. Barcode1DEncoderInterface obsługuje symboliki liniowe, w tym Code 128 i EAN-13, oraz zwraca obiekt wartości BarcodeData. Barcode2DEncoderInterface obsługuje symboliki macierzowe, w tym QR Code (Quick Response) oraz Data Matrix. Zwraca obiekt wartości Barcode2DData z mapą opcji obejmującą ustawienia specyficzne dla symboliki, takie jak poziom korekcji błędów.

BarcodeEncoderInterface to ogólny kontrakt dostawcy usług. Implementuje go każdy koder 2D wykrywany przez BarcodeEncoderRegistry. Kontrakt zwraca albo monochromatyczną macierz Barcode2DData, albo kolorową macierz BarcodeColorData, dzięki czemu zarejestrowany koder może wytworzyć kolorowy symbol bez osobnego interfejsu. Kodery powinny być bezstanowe poza konfiguracją przekazaną podczas konstrukcji. Rejestr zwraca jedną współdzieloną instancję dla każdego zarejestrowanego typu, więc każdy stan zależny od wywołania byłby wadą.

Gs1DataParserInterface to kontrakt danych ustrukturyzowanych. Parsuje łańcuch elementów GS1 do typowanego obiektu, a następnie ponownie koduje ten obiekt dla nośnika QR Code, Data Matrix lub Code 128. Dzięki temu gramatyka GS1 pozostaje oddzielona od symboliki. Parser jednokrotnie waliduje identyfikatory zastosowania (Application Identifiers). Metody specyficzne dla nośnika formatują tę samą sparsowaną strukturę dla każdego z tych celów. Wszystkie cztery kontrakty są stable. BarcodeEncoderInterface jest stabilny od wersji 3.0.0; pozostałe od wersji 1.0.0. Nowe metody są dodawane wyłącznie z domyślnymi implementacjami.

Powierzchnia API

Typ	Rodzaj	Kluczowe składowe	Stabilność	Od wersji
Barcode1DEncoderInterface	interfejs	encode(string): BarcodeData	stabilny	1.0.0
Barcode2DEncoderInterface	interfejs	encode(string, array): Barcode2DData	stabilny	1.0.0
BarcodeEncoderInterface	interfejs	encode(string, array): Barcode2DData|BarcodeColorData	stabilny	3.0.0
Gs1DataParserInterface	interfejs	parse(), encodeForQrCode(), encodeForDataMatrix(), encodeForCode128()	stabilny	1.0.0

W kontraktach 2D tablica $options jest specyficzna dla symboliki; przykładem jest poziom korekcji błędów dla QR Code. Kontrakt nie ogranicza jej kluczy. Każdy zarejestrowany koder dokumentuje własny zestaw opcji.

Przykład kodu — szybki start

examples/10-barcodes.php

<?php

declare(strict_types=1);

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

use NextPDF\Barcode\Barcode2DType;
use NextPDF\Barcode\BarcodeType;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Barcode Examples');
$doc->addPage();

$doc->setFont('helvetica', '', 10);
$doc->cell(0, 6, 'Code 128:', newLine: true);
$doc->write1DBarcode('NEXTPDF-2026', BarcodeType::C128, x: 15, y: null, w: 80, h: 20);
$doc->ln(28);

$doc->cell(0, 6, 'QR Code (URL):', newLine: true);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: null, w: 40, h: 40);

$doc->save(__DIR__ . '/output/10-barcodes.pdf');

write1DBarcode() i write2DBarcode() uzyskują koder za pośrednictwem rejestru. Kod aplikacji rzadko sięga po kontrakty bezpośrednio. Wskazujesz symbolikę, a rejestr dostarcza koder.

Przykład kodu — produkcja

examples/contracts/barcode-production.php

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Barcode2DEncoderInterface;
use NextPDF\Contracts\Gs1DataParserInterface;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class Gs1LabelService
{
    public function __construct(
        private Gs1DataParserInterface $parser,
        private Barcode2DEncoderInterface $dataMatrix,
        private LoggerInterface $logger,
    ) {}

    /**
     * Parse a GS1 element string and encode it as a Data Matrix.
     *
     * @param string $elementString A GS1 element string with Application Identifiers.
     */
    public function encodeLabel(string $elementString): \NextPDF\Barcode\Barcode2DData
    {
        try {
            $parsed = $this->parser->parse($elementString);
            $payload = $this->parser->encodeForDataMatrix($parsed);

            return $this->dataMatrix->encode($payload, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('GS1 label encoding failed', [
                'error' => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

Usługa zależy od kontraktów parsera i kodera. Blok catch rejestruje konkretny wyjątek BarcodeException i zgłasza go ponownie; nigdy nie przechwytuje samego \Exception.

Przypadki brzegowe i pułapki

• Zarejestrowany koder jest współdzielony. Stan zależny od wywołania w koderze powoduje błędy przy równoległym renderowaniu. Kodery powinny pozostawać bezstanowe poza konfiguracją konstruktora.
• BarcodeEncoderInterface::encode() może zwrócić dane kolorowe albo monochromatyczne. Kod, który go używa, musi obsłużyć zarówno Barcode2DData, jak i BarcodeColorData, a nie zakładać monochromii.
• Tablica $options 2D nie jest walidowana przez kontrakt. Większość koderów ignoruje nieznane klucze bez sygnalizowania błędu. Sprawdź nazwę klucza w dokumentacji danego kodera.
• Parsowanie GS1 jest ściśle zgodne z gramatyką. Dla łańcucha elementów z nieznanym identyfikatorem zastosowania (Application Identifier) parser zgłasza BarcodeException zamiast zwracać częściowy wynik parsowania. Waliduj dane wejściowe na wcześniejszym etapie.
• Kontrakty 1D i 2D nie są wymienne. Przekazanie ładunku QR do kodera 1D utworzy nieprawidłowy symbol. Rejestr dobiera koder według typu symboliki, więc preferuj rejestr zamiast bezpośredniego wywołania kontraktu.

Wydajność

Koszt kodowania skaluje się z długością ładunku i rozmiarem docelowej macierzy, a nie z wywoływanym kontraktem. Krótki ładunek Code 128 koduje się w mikrosekundach. Gęsty QR Code z wysoką korekcją błędów to najcięższy przypadek 2D. Mimo to mieści się z zapasem w performance_budget wynoszącym 1500 ms czasu rzeczywistego i 64 MB szczytowego zużycia pamięci dla przykładowej strony z wieloma symbolami. Macierz jest obliczana raz i rysowana jako operatory PDF. Powtarzalność ma wartość bitwise, ponieważ ten sam ładunek i opcje zawsze dają tę samą macierz modułów. Wyszukiwanie w rejestrze ma złożoność O(1). Faktyczną pracę wykonuje algorytm symboliki.

Uwagi dotyczące bezpieczeństwa

Ładunki kodów kreskowych często mogą pozostawać pod kontrolą atakującego: może to być zeskanowany adres URL, numer seryjny lub kod śledzenia. Kontrakty kodują bajty i ich nie interpretują. QR Code kodujący wrogi adres URL nadal jest prawidłowym kodem QR, więc zaufanie do ładunku spoczywa na konsumencie, a nie na koderze. Ogranicz długość ładunku przed kodowaniem, aby kontrolować rozmiar macierzy i uniknąć odmowy usługi (denial-of-service) spowodowanej nadmiernie dużym symbolem. Parser GS1 odrzuca nieprawidłowe identyfikatory zastosowania (Application Identifiers), co usuwa jedną z powierzchni wstrzykiwania. Nie waliduje semantycznej zawartości prawidłowych pól. Traktuj zdekodowane dane kodu kreskowego jako niezaufane dane wejściowe wszędzie tam, gdzie ponownie trafiają do aplikacji.

Zgodność

Deklaracja	Norma	Odniesienie
Symbole QR Code są zgodne ze specyfikacją symboliki macierzowej QR Code.	ISO/IEC 18004	Symbolika QR Code
Symbole Data Matrix są zgodne ze specyfikacją symboliki Data Matrix.	ISO/IEC 16022	Symbolika Data Matrix
Symbole Code 128 są zgodne ze specyfikacją liniowej symboliki Code 128.	ISO/IEC 15417	Symbolika Code 128
Łańcuchy elementów GS1 są parsowane zgodnie z gramatyką identyfikatorów zastosowania GS1.	GS1 General Specifications	Identyfikatory zastosowania

Te normy są przywoływane z podaniem numeru i klauzuli. Nie występują w weryfikowalnym korpusie cytowań, więc nie jest rejestrowany żaden reference_id. Silnik parafrazuje wymaganie i wskazuje źródło. Aby poznać miarodajne reguły kodowania, skorzystaj z opublikowanych norm.

Kontekst komercyjny

Core definiuje i zamraża kontrakty koderów oraz udostępnia najczęściej używane symboliki. Edycje Pro i Enterprise rejestrują rozszerzony zestaw koderów dla dodatkowych symbolik kodów kreskowych w ramach tego samego BarcodeEncoderInterface, dzięki czemu wdrożenie komercyjne zyskuje pokrycie bez zmiany interfejsu programowania aplikacji (API). Core pobiera zarejestrowane kodery za pośrednictwem BarcodeEncoderRegistry. Interfejs kontraktu jest identyczny we wszystkich edycjach.

Zobacz też

• Kontrakty: 41 publicznych interfejsów (SPI) — przegląd interfejsu dostawcy usług (SPI) oraz poziomy stabilności.
• Barcode — implementacje symbolik zarejestrowane dla tych kontraktów.
• Contracts / Document — PdfDocumentInterface, który rysuje zakodowaną macierz.
• Graphics — warstwa rysowania renderująca moduły kodu kreskowego.
• Exception — BarcodeException zgłaszany przy nieprawidłowych danych wejściowych GS1.