Contracts / Barcode

In het kort

Het barcodedomein definieert vier contracts: een eendimensionale (1D) encoder, een tweedimensionale (2D) encoder, een generieke encoder die via de registry vindbaar is en een GS1-dataparser. Samen bepalen ze de vorm waaraan barcodeservices moeten voldoen. Symbologie-implementaties registreren zich op deze contracts.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

Een barcode-encoder zet een payloadtekenreeks om in de modulematrix die de Portable Document Format (PDF)-writer tekent. NextPDF splitst encodercontracts op per dimensionaliteit. Barcode1DEncoderInterface verwerkt lineaire symbologieën, waaronder Code 128 en EAN-13, en retourneert een BarcodeData-waardeobject. Barcode2DEncoderInterface verwerkt matrixsymbologieën, waaronder Quick Response (QR) Code en Data Matrix. Die retourneert een Barcode2DData-waardeobject met een optiemap voor symbologiespecifieke instellingen, zoals het foutcorrectieniveau.

BarcodeEncoderInterface is het generieke service-provider-contract. Elke 2D-encoder die via BarcodeEncoderRegistry vindbaar is, implementeert dit contract. Het contract retourneert ofwel een monochrome Barcode2DData ofwel een gekleurde BarcodeColorData-matrix, zodat een geregistreerde encoder een gekleurd symbool kan produceren zonder een aparte interface. Afgezien van configuratie tijdens constructie worden encoders geacht statusloos te zijn. De registry retourneert één gedeelde instantie per geregistreerd type, dus elke status per aanroep zou een defect zijn.

Gs1DataParserInterface is het contract voor gestructureerde data. Het parseert een GS1-elementtekenreeks naar een getypeerd object en hercodeert dat object vervolgens voor een drager in de vorm van een QR Code, een Data Matrix of een Code 128. Zo blijft de GS1-grammatica gescheiden van de symbologie. De parser valideert Application Identifiers één keer. De dragerspecifieke methoden formatteren dezelfde geparseerde structuur voor elk doel. De vier contracts zijn stable. BarcodeEncoderInterface is stable sinds 3.0.0; de andere sinds 1.0.0. Nieuwe methoden komen uitsluitend met standaardimplementaties.

API-oppervlak

Type	Soort	Belangrijkste members	Stabiliteit	Sinds
Barcode1DEncoderInterface	interface	encode(string): BarcodeData	stable	1.0.0
Barcode2DEncoderInterface	interface	encode(string, array): Barcode2DData	stable	1.0.0
BarcodeEncoderInterface	interface	encode(string, array): Barcode2DData|BarcodeColorData	stable	3.0.0
Gs1DataParserInterface	interface	parse(), encodeForQrCode(), encodeForDataMatrix(), encodeForCode128()	stable	1.0.0

Bij de 2D-contracts is de $options-array symbologiespecifiek, zoals een foutcorrectieniveau voor QR Code. Het contract legt geen beperkingen op aan de sleutels. Elke geregistreerde encoder documenteert zijn eigen optieset.

Codevoorbeeld — Snelstart

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() en write2DBarcode() vinden een encoder via de registry. Je applicatiecode komt zelden rechtstreeks met de contracts in aanraking. Je geeft een symbologie op en de registry levert de encoder.

Codevoorbeeld — Productie

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;
        }
    }
}

De service is afhankelijk van de parser- en encodercontracts. Het catch-blok logt de specifieke BarcodeException en gooit die opnieuw; het vangt nooit een algemene \Exception op.

Randgevallen en valkuilen

• Een geregistreerde encoder wordt gedeeld. Status per aanroep op een encoder beschadigt gelijktijdige renders. Houd encoders, afgezien van constructorconfiguratie, statusloos.
• BarcodeEncoderInterface::encode() kan gekleurde of monochrome data retourneren. Code die dit resultaat verbruikt, moet zowel Barcode2DData als BarcodeColorData verwerken en niet uitgaan van monochroom.
• De 2D-$options-array wordt niet door het contract gevalideerd. De meeste encoders negeren onbekende sleutels stilzwijgend. Controleer de sleutelnaam aan de hand van de eigen documentatie van de encoder.
• GS1-parsing volgt de grammatica strikt. Een elementtekenreeks met een onbekende Application Identifier veroorzaakt een BarcodeException in plaats van een gedeeltelijke parse op te leveren. Valideer invoer stroomopwaarts.
• 1D- en 2D-contracts zijn niet uitwisselbaar. Een QR-payload aan een 1D-encoder doorgeven levert een ongeldig symbool op. De registry routeert op symbologietype, dus geef de voorkeur aan de registry in plaats van een directe contractaanroep.

Prestaties

De coderingskosten schalen mee met de payloadlengte en de doelmatrixgrootte, niet met het contract dat je aanroept. Een korte Code 128-payload codeert in microseconden. Een dichte QR Code met hoge foutcorrectie is het zwaarste 2D-geval. Dat blijft ruim binnen het performance_budget van 1500 ms wandkloktijd en 64 MB piek voor de voorbeeldpagina met meerdere symbolen. De matrix wordt één keer berekend en als PDF-operators getekend. Reproduceerbaarheid is bitwise omdat dezelfde payload en opties altijd dezelfde modulematrix opleveren. Het opzoeken in de registry is O(1). Het werk zit in het symbologie-algoritme.

Beveiligingsnotities

Barcodepayloads komen vaak uit invoer die een aanvaller kan beïnvloeden, zoals een gescande Uniform Resource Locator (URL), een serienummer of een trackingcode. De contracts coderen bytes. Ze interpreteren deze niet. Een QR Code die een vijandige URL codeert, is nog steeds een geldige QR Code, dus vertrouwen in de payload is de verantwoordelijkheid van de consument, niet van de encoder. Beperk de payloadlengte vóór het coderen om de matrixgrootte te begrenzen en een denial-of-service via een te groot symbool te voorkomen. De GS1-parser weigert misvormde Application Identifiers, wat één injectieoppervlak wegneemt. De parser valideert de semantische inhoud van geldige velden niet. Behandel gedecodeerde barcodegegevens als niet-vertrouwde invoer, overal waar deze de applicatie opnieuw binnenkomen.

Conformiteit

Bewering	Standaard	Referentie
QR Code-symbolen volgen de specificatie voor de QR Code-matrixsymbologie.	ISO/IEC 18004	QR Code-symbologie
Data Matrix-symbolen volgen de specificatie voor de Data Matrix-symbologie.	ISO/IEC 16022	Data Matrix-symbologie
Code 128-symbolen volgen de specificatie voor de lineaire Code 128-symbologie.	ISO/IEC 15417	Code 128-symbologie
GS1-elementtekenreeksen worden geparseerd volgens de grammatica van de GS1 Application Identifier.	GS1 General Specifications	Application Identifiers

Naar deze standaarden wordt verwezen met nummer en clausule. Ze zijn niet aanwezig in het verifieerbare citatiecorpus, dus er wordt geen reference_id vastgelegd. De engine parafraseert de vereiste en citeert de bron. Raadpleeg de gepubliceerde standaarden voor gezaghebbende coderingsregels.

Commerciële context

Core definieert en bevriest de encodercontracts en levert de gangbare symbologieën. De Pro- en Enterprise-edities registreren een uitgebreide encoderset voor aanvullende barcodesymbologieën op dezelfde BarcodeEncoderInterface, zodat een commerciële implementatie dekking krijgt zonder wijziging van de application programming interface (API). Core vindt geregistreerde encoders via BarcodeEncoderRegistry. Het contractoppervlak is identiek in alle edities.

Zie ook

• Contracts: 41 publieke interfaces (SPI) — het overzicht van de service provider interface (SPI) en de stabiliteitsniveaus.
• Barcode — de symbologie-implementaties die op deze contracts geregistreerd zijn.
• Contracts / Document — PdfDocumentInterface die de gecodeerde matrix tekent.
• Graphics — de tekenlaag die barcodemodules weergeeft.
• Exception — BarcodeException die bij misvormde GS1-invoer wordt gegooid.