Barcode: kodery symbolik 1D i 2D

W skrócie

Moduł Barcode dostarcza warstwę implementacji symbolik. Koduje symboliki liniowe (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, kody pocztowe) oraz symboliki macierzowe (QR Code, Data Matrix, PDF417). Oblicza korekcję błędów i rejestruje każdy koder przez kontrakty kodów kreskowych, aby moduł zapisujący dokument mógł narysować wynik. Definicje kontraktów znajdują się na osobnej stronie. Zobacz uwagę poniżej.

Jedna kanoniczna strona na zagadnienie. Interfejsy implementowane przez kodery (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) są udokumentowane na Contracts / Barcode. Ta strona dokumentuje konkretne kodery implementujące te kontrakty. Strony się uzupełniają, nie są duplikatami. Przeczytaj stronę z kontraktami, aby poznać interfejs dostawcy usługi (SPI). Przeczytaj tę stronę, aby poznać symboliki.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Koder kodu kreskowego zamienia ładunek tekstowy na dwuwymiarową (2D) macierz modułów albo jednowymiarową (1D) sekwencję pasków, którą moduł zapisujący renderuje jako grafikę Portable Document Format (PDF). Ten moduł dostarcza konkretne kodery.

Barcode1D to silnik liniowy. BarcodeType zawiera obsługiwane symboliki liniowe: Code 39 (z sumą kontrolną i bez niej), Code 93, rodzinę Code 128, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved oraz Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB) i MSI. generate() zwraca obiekt wartości BarcodeData opisujący wzór pasków.

Kodery 2D — QrEncoder, DataMatrixEncoder oraz Pdf417Encoder — implementują BarcodeEncoderInterface i zwracają macierz Barcode2DData. Barcode2DType zawiera symboliki macierzowe rozpoznawane przez silnik, w tym QR Code, Data Matrix oraz PDF417. Dodatkowe symboliki, takie jak Micro QR, rMQR, GS1 DataBar i Han Xin, są ujęte w wyliczeniu na potrzeby routingu w rejestrze. To, które kodery obsługują daną symbolikę, zależy od edycji. Korekcja błędów macierzy jest obliczana nad ciałem Galois. GaloisField i GaloisFieldPrime dostarczają arytmetykę Reeda–Solomona współdzieloną przez kodery QR, Data Matrix i PDF417.

BarcodeEncoderRegistry to mechanizm wyszukiwania. Implementuje on ContainerInterface z PHP Standards Recommendation 11 (PSR-11), udostępnia domyślną rejestrację przez createDefault() i rozwiązuje symbolikę do odpowiadającego jej kodera za pomocą resolve(). Kod aplikacji rzadko sięga po koder bezpośrednio. Wysokopoziomowa fasada Document::write1DBarcode() / write2DBarcode() wskazuje symbolikę, a rejestr dostarcza koder. Silnik 1D jest @since 1.0.0. Kodery 2D są @since 1.3.0. Rejestr jest @since 3.0.0.

Powierzchnia API

Klasa	Kluczowe składowe	Rola
`Barcode1D`	`generate(string $code, BarcodeType $type): BarcodeData`	Koder symbolik liniowych (`@since 1.0.0`)
`QrEncoder`	`encode(string $data, array $options = []): Barcode2DData`	Koder QR Code (`@since 1.3.0`)
`DataMatrixEncoder`	`encode(string $data, array $options = []): Barcode2DData`	Koder Data Matrix (`@since 1.3.0`)
`Pdf417Encoder`	`encode(string $data, array $options = []): Barcode2DData`	Koder PDF417 (`@since 1.3.0`)
`BarcodeEncoderRegistry`	`createDefault()`, `register()`, `resolve()`, `has()`, `get()`, `registered()`	Rejestr koderów PSR-11 (`@since 3.0.0`)
`BarcodeType` / `Barcode2DType`	przypadki enum	Wyliczenia dla obsługiwanych symbolik
`GaloisField` / `GaloisFieldPrime`	arytmetyka ciała skończonego	Korekcja błędów Reeda–Solomona

Uruchom composer docs:generate-api-php -- --module=Barcode, aby wygenerować pełną tabelę PHPDoc.

Przykład kodu — Szybki start

Źródło: examples/10-barcodes.php. Fasada rozwiązuje koder żądanej symboliki za pośrednictwem rejestru.

<?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->addPage();

$doc->write1DBarcode('4006381333931', BarcodeType::EAN13, x: 15, y: null, w: 60, h: 20);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: 40, w: 40, h: 40);

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

Przykład kodu — Produkcja

Rozwiąż koder 2D bezpośrednio przez rejestr i ogranicz ładunek przed zakodowaniem.

<?php

declare(strict_types=1);

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

use NextPDF\Barcode\Barcode2DType;
use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class TrackingCodeService
{
    private const int MAX_PAYLOAD = 512;

    public function __construct(
        private BarcodeEncoderRegistry $registry,
        private LoggerInterface $logger,
    ) {}

    /** @return \NextPDF\Barcode\Barcode2DData */
    public function encode(string $trackingId): \NextPDF\Barcode\Barcode2DData
    {
        if (strlen($trackingId) > self::MAX_PAYLOAD) {
            throw new \LengthException('Tracking payload exceeds the encode bound.');
        }

        try {
            $encoder = $this->registry->resolve(Barcode2DType::QRCode->value);

            return $encoder->encode($trackingId, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('Barcode encode failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

Przypadki brzegowe i pułapki

Ładunek liniowy, który narusza zestaw znaków symboliki lub regułę cyfry kontrolnej, powoduje zgłoszenie BarcodeException. EAN/UPC obliczają i dołączają cyfrę kontrolną. Nie dołączaj jej wcześniej.
Tablica $options dla kodów 2D zależy od symboliki, na przykład od poziomu korekcji błędów dla QR. Większość koderów ignoruje nieznane klucze. Sprawdź każdy klucz w dokumentacji danego kodera.
Barcode2DType zawiera więcej symbolik, niż edycja core dostarcza koderów. BarcodeEncoderRegistry::resolve() zgłasza wyjątek dla niezarejestrowanej symboliki, zamiast zwracać element zastępczy.
Zarejestrowane kodery to instancje współdzielone. Utrzymuj je bezstanowymi poza konfiguracją z konstruktora. Stan na poziomie pojedynczego wywołania psuje współbieżne renderowania.
Zbyt długi ładunek powoduje utworzenie gęstszej, większej macierzy. Ogranicz długość ładunku przed zakodowaniem, aby uniknąć odmowy usługi spowodowanej rozmiarem symbolu.

Wydajność

Koszt kodowania skaluje się z długością ładunku i rozmiarem macierzy, a nie z wyszukiwaniem w rejestrze, które ma złożoność O(1). Krótki ładunek Code 128 koduje się w mikrosekundach. Gęsty QR Code z wysokim poziomem korekcji błędów to najcięższy przypadek. Strona przykładu z wieloma symbolami mieści się w budżecie 1500 ms czasu wykonania i 64 MB szczytowego użycia pamięci. Profil odtwarzalności to bitwise. Ten sam ładunek i te same opcje zawsze tworzą tę samą macierz modułów oraz te same narysowane bajty.

Uwagi dotyczące bezpieczeństwa

Ładunki kodów kreskowych często pochodzą z niezaufanych źródeł: zeskanowanego ujednoliconego lokalizatora zasobów (URL), numeru seryjnego lub kodu śledzenia. Kodery kodują bajty. Nie interpretują ich. QR Code, który koduje złośliwy URL, nadal jest poprawnym QR Code, więc to konsument odpowiada za zaufanie do ładunku. Ogranicz długość ładunku przed zakodowaniem, aby utrzymać rozmiar macierzy, nakład pracy i rozmiar wyniku w ramach budżetu. Traktuj wszelkie dane zdekodowane z kodu kreskowego w innym miejscu jako niezaufane dane wejściowe, gdy ponownie trafiają do aplikacji. Zobacz model zagrożeń silnika w /modules/core/security/.

Zgodność

Twierdzenie	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 PDF417 są zgodne ze specyfikacją symboliki PDF417.	ISO/IEC 15438	symbolika PDF417
Symbole Code 128 są zgodne ze specyfikacją liniowej symboliki Code 128.	ISO/IEC 15417	symbolika Code 128
Symbole EAN/UPC są zgodne ze specyfikacją symboliki EAN/UPC.	ISO/IEC 15420	symbolika EAN/UPC

Te normy symbolik nie występują w weryfikowalnym korpusie cytowań, więc nie zapisano żadnego reference_id. Ta strona parafrazuje wymaganie i przywołuje źródło przez numer oraz klauzulę. Aby poznać wiążące reguły kodowania, zapoznaj się z opublikowanymi normami. Kodery są sprawdzane przez tests/Unit/Barcode/. Za poprawność względem specyfikacji symbolik odpowiada zestaw testów, a nie twierdzenie o kompleksowej zgodności PDF.

Zobacz także

Contracts / Barcode — interfejsy koderów, które implementują te klasy (SPI).
Moduł Graphics — warstwa rysowania, która renderuje zakodowaną macierz.
Moduł Document — wysokopoziomowa fasada write1DBarcode() / write2DBarcode().
Przegląd zgodności
Model bezpieczeństwa silnika