Barcode: encoders voor 1D- en 2D-symbologieën

In het kort

De Barcode-module levert de implementatielaag voor symbologieën. Hij codeert lineaire symbologieën (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, postcodes) en matrixsymbologieën (QR Code, Data Matrix, PDF417). Hij berekent foutcorrectie en registreert elke encoder achter de barcodecontracten, zodat de document-writer het resultaat kan tekenen. De contractdefinities staan op een aparte pagina. Zie de opmerking hieronder.

Eén canonieke pagina per onderwerp. De interfaces waaraan een encoder voldoet (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) zijn gedocumenteerd op Contracts / Barcode. Deze pagina documenteert de concrete encoders die deze contracten implementeren. De pagina’s zijn complementair en geen duplicaten. Lees de contractenpagina voor de service provider interface (SPI). Lees deze pagina voor de symbologieën.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

Een barcode-encoder zet een payload-string om in een tweedimensionale (2D) modulematrix of een eendimensionale (1D) balksequentie die de writer als Portable Document Format-graphics (PDF) tekent. Deze module levert de concrete encoders.

Barcode1D is de lineaire engine. BarcodeType somt de ondersteunde lineaire symbologieën op: Code 39 (met en zonder checksum), Code 93, de Code 128-familie, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved en Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB) en MSI. generate() retourneert een BarcodeData-waardeobject dat het balkpatroon beschrijft.

De 2D-encoders, QrEncoder, DataMatrixEncoder en Pdf417Encoder, implementeren BarcodeEncoderInterface en retourneren een Barcode2DData-matrix. Barcode2DType somt de matrixsymbologieën op die de engine herkent, waaronder QR Code, Data Matrix en PDF417. Aanvullende symbologieën zoals Micro QR, rMQR, GS1 DataBar en Han Xin staan in de lijst voor registry-routing. Welke encoders een symbologie ondersteunen, hangt af van de editie. Matrixfoutcorrectie wordt berekend over een Galois-veld. GaloisField en GaloisFieldPrime leveren de Reed-Solomon-rekenkunde die de QR-, Data Matrix- en PDF417-encoders delen.

BarcodeEncoderRegistry is de lookup. Hij implementeert PHP Standards Recommendation 11 (PSR-11) ContainerInterface, biedt standaardregistratie via createDefault() en resolvet een symbologie naar de bijbehorende encoder met resolve(). Applicatiecode spreekt een encoder zelden rechtstreeks aan. De high-level Document::write1DBarcode() / write2DBarcode()-facade geeft een symbologie op, waarna de registry de encoder levert. De 1D-engine is @since 1.0.0. De 2D-encoders zijn @since 1.3.0. De registry is @since 3.0.0.

API-oppervlak

Class	Belangrijkste members	Rol
Barcode1D	generate(string $code, BarcodeType $type): BarcodeData	Encoder voor lineaire symbologieën (@since 1.0.0)
QrEncoder	encode(string $data, array $options = []): Barcode2DData	QR Code-encoder (@since 1.3.0)
DataMatrixEncoder	encode(string $data, array $options = []): Barcode2DData	Data Matrix-encoder (@since 1.3.0)
Pdf417Encoder	encode(string $data, array $options = []): Barcode2DData	PDF417-encoder (@since 1.3.0)
BarcodeEncoderRegistry	createDefault(), register(), resolve(), has(), get(), registered()	PSR-11 encoder registry (@since 3.0.0)
BarcodeType / Barcode2DType	enum-cases	Ondersteunde symbologie-enumeraties
GaloisField / GaloisFieldPrime	rekenkunde voor eindige velden	Reed-Solomon-foutcorrectie

Voer composer docs:generate-api-php -- --module=Barcode uit om de volledige PHPDoc-tabel te genereren.

Codevoorbeeld — Snelstart

Bron: examples/10-barcodes.php. De facade laat de registry de encoder voor de gevraagde symbologie resolven.

<?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');

Codevoorbeeld — Productie

Resolveer een 2D-encoder rechtstreeks via de registry en begrens de payload vóór het coderen.

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

Randgevallen en valkuilen

• Een lineaire payload die niet voldoet aan de tekenset of de controlecijferregel van een symbologie veroorzaakt BarcodeException. EAN/UPC berekenen het controlecijfer en voegen het toe. Voeg het niet vooraf zelf toe.
• De 2D-array $options is symbologiespecifiek, bijvoorbeeld voor een foutcorrectieniveau bij QR. De meeste encoders negeren onbekende sleutels. Controleer elke sleutel in de eigen documentatie van de encoder.
• Barcode2DType somt meer symbologieën op dan de core-editie als encoders meelevert. BarcodeEncoderRegistry::resolve() veroorzaakt een fout voor een niet-geregistreerde symbologie in plaats van een placeholder te retourneren.
• Geregistreerde encoders zijn gedeelde instances. Houd ze, afgezien van constructorconfiguratie, stateless. State per aanroep beschadigt gelijktijdige renders.
• Een te lange payload levert een dichtere, grotere matrix op. Begrens de payloadlengte vóór het coderen om denial of service via symboolgrootte te voorkomen.

Prestaties

De codeerkosten schalen mee met de payloadlengte en de matrixgrootte, niet met de registry-lookup, die O(1) is. Een korte Code 128-payload codeert in microseconden. Een dichte QR Code met hoge foutcorrectie is het zwaarste geval. De voorbeeldpagina met meerdere symbolen blijft binnen het budget van 1500 ms wall / 64 MB piek. Het reproduceerbaarheidsprofiel is bitwise. Dezelfde payload en opties leveren altijd dezelfde modulematrix en dezelfde getekende bytes op.

Beveiligingsopmerkingen

Barcode-payloads komen vaak uit niet-vertrouwde bronnen: een gescande uniform resource locator (URL), een serienummer of een trackingcode. De encoders coderen bytes; ze interpreteren ze niet. Een QR Code die een kwaadaardige URL codeert, is nog steeds een geldige QR Code, dus de consument is verantwoordelijk voor het vertrouwen in de payload. Begrens de payloadlengte vóór het coderen om de matrixgrootte, de hoeveelheid werk en de uitvoergrootte binnen een budget te houden. Behandel gegevens die elders uit een barcode zijn gedecodeerd als niet-vertrouwde invoer wanneer ze de applicatie weer binnenkomen. Zie het dreigingsmodel van de engine in /modules/core/security/.

Conformiteit

Claim	Standaard	Referentie
QR Code-symbolen volgen de QR Code-matrixsymbologiespecificatie.	ISO/IEC 18004	QR Code-symbologie
Data Matrix-symbolen volgen de Data Matrix-symbologiespecificatie.	ISO/IEC 16022	Data Matrix-symbologie
PDF417-symbolen volgen de PDF417-symbologiespecificatie.	ISO/IEC 15438	PDF417-symbologie
Code 128-symbolen volgen de lineaire Code 128-symbologiespecificatie.	ISO/IEC 15417	Code 128-symbologie
EAN/UPC-symbolen volgen de EAN/UPC-symbologiespecificatie.	ISO/IEC 15420	EAN/UPC-symbologie

Deze symbologiestandaarden zijn niet aanwezig in het verifieerbare citatiecorpus, dus er wordt geen reference_id vastgelegd. Deze pagina parafraseert de eis en citeert de bron op nummer en clausule. Raadpleeg de gepubliceerde standaarden voor de gezaghebbende coderingsregels. De encoders worden getest door tests/Unit/Barcode/. Correctheid ten opzichte van de symbologiespecificaties is de verantwoordelijkheid van de testsuite, geen uitspraak over end-to-end PDF-conformiteit.

Zie ook

• Contracts / Barcode — de encoder-interfaces die deze classes implementeren (de SPI).
• Graphics-module — de tekenlaag die de gecodeerde matrix tekent.
• Document-module — de high-level write1DBarcode() / write2DBarcode()-facade.
• Conformiteitsoverzicht
• Beveiligingsmodel van de engine