Barcode: encoder per simbologie 1D e 2D

In breve

Il modulo Barcode è il livello di implementazione delle simbologie. Codifica simbologie lineari (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, codici postali) e simbologie a matrice (QR Code, Data Matrix, PDF417). Ne calcola la correzione d’errore. Registra ciascun encoder dietro i contratti barcode, così che il writer del documento possa disegnare il risultato. Le definizioni dei contratti risiedono in una pagina separata. Consultare la nota seguente.

Una sola pagina canonica per ogni argomento. Le interfacce che un encoder soddisfa (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) sono documentate in Contratti / Barcode. Questa pagina documenta gli encoder concreti che implementano tali contratti. Le due pagine sono complementari, non duplicate. Consultare la pagina dei contratti per l’SPI. Consultare questa pagina per le simbologie.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Un encoder di barcode trasforma una stringa di payload in una matrice di moduli (2D) o in una sequenza di barre (1D), che il writer disegna come grafica PDF. Questo modulo fornisce gli encoder concreti.

Barcode1D è il motore lineare. BarcodeType elenca le simbologie lineari supportate — Code 39 (con e senza checksum), Code 93, la famiglia Code 128, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved e Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB) e MSI. generate() restituisce un value object BarcodeData che descrive il pattern delle barre.

Gli encoder 2D — QrEncoder, DataMatrixEncoder, Pdf417Encoder — implementano BarcodeEncoderInterface e restituiscono una matrice Barcode2DData. Barcode2DType elenca le simbologie a matrice riconosciute dal motore, tra cui QR Code, Data Matrix e PDF417. Simbologie aggiuntive come Micro QR, rMQR, GS1 DataBar e Han Xin sono enumerate per l’instradamento del registry. L’insieme di encoder che le supporta dipende dall’edizione. La correzione d’errore della matrice è calcolata su un campo di Galois. GaloisField e GaloisFieldPrime forniscono l’aritmetica Reed-Solomon condivisa dagli encoder QR, Data Matrix e PDF417.

BarcodeEncoderRegistry è il punto di lookup. Implementa la ContainerInterface PSR-11, fornisce una registrazione predefinita tramite createDefault() e risolve una simbologia nel relativo encoder con resolve(). Il codice applicativo accede di rado direttamente a un encoder. La facade di alto livello Document::write1DBarcode() / write2DBarcode() indica una simbologia e il registry fornisce l’encoder. Il motore 1D è @since 1.0.0. Gli encoder 2D sono @since 1.3.0. Il registry è @since 3.0.0.

Superficie API

Classe	Membri chiave	Ruolo
Barcode1D	generate(string $code, BarcodeType $type): BarcodeData	Encoder di simbologie lineari (@since 1.0.0)
QrEncoder	encode(string $data, array $options = []): Barcode2DData	Encoder QR Code (@since 1.3.0)
DataMatrixEncoder	encode(string $data, array $options = []): Barcode2DData	Encoder Data Matrix (@since 1.3.0)
Pdf417Encoder	encode(string $data, array $options = []): Barcode2DData	Encoder PDF417 (@since 1.3.0)
BarcodeEncoderRegistry	createDefault(), register(), resolve(), has(), get(), registered()	Registry di encoder PSR-11 (@since 3.0.0)
BarcodeType / Barcode2DType	casi dell’enum	Enumerazioni delle simbologie supportate
GaloisField / GaloisFieldPrime	aritmetica su campi finiti	Correzione d’errore Reed-Solomon

Eseguire composer docs:generate-api-php -- --module=Barcode per la tabella PHPDoc completa.

Esempio di codice — Avvio rapido

Sorgente: examples/10-barcodes.php. La facade risolve un encoder tramite il registry in base alla simbologia.

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

Esempio di codice — Produzione

Risolvere direttamente un encoder 2D tramite il registry e limitare il payload prima della codifica.

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

Casi limite e insidie

• Se un payload lineare viola il set di caratteri o la regola del check digit di una simbologia, viene sollevata BarcodeException. EAN/UPC calcolano e accodano il check digit. Non anteporlo.
• L’array 2D $options dipende dalla simbologia (per esempio, un livello di correzione d’errore per QR). Le chiavi sconosciute sono ignorate dalla maggior parte degli encoder. Verificare la chiave rispetto alla documentazione dell’encoder stesso.
• Barcode2DType enumera più simbologie di quelle per cui l’edizione core fornisce encoder. BarcodeEncoderRegistry::resolve() solleva un’eccezione per una simbologia non registrata invece di restituire un segnaposto.
• Gli encoder registrati sono istanze condivise. Mantenerli privi di stato oltre alla configurazione del costruttore. Lo stato relativo a una singola chiamata corrompe i rendering concorrenti.
• Un payload troppo lungo produce una matrice più densa e più grande. Limitare la lunghezza del payload prima della codifica per evitare un denial of service tramite la dimensione del simbolo.

Prestazioni

Il costo di codifica scala con la lunghezza del payload e la dimensione della matrice, non con il lookup nel registry, che è O(1). Un breve payload Code 128 si codifica in microsecondi. Un QR Code denso con correzione d’errore elevata è il caso più oneroso. Rientra nel budget di 1500 ms di tempo / 64 MB di picco per la pagina di esempio multi-simbolo. Il profilo di riproducibilità è bitwise. Lo stesso payload e le stesse opzioni producono sempre la stessa matrice di moduli e gli stessi byte disegnati.

Note di sicurezza

I payload dei barcode sono spesso influenzati da un aggressore — un URL scansionato, un numero di serie, un codice di tracciamento. Gli encoder codificano byte. Non li interpretano. Un QR Code che codifica un URL ostile è un QR Code valido, quindi l’affidabilità del payload è responsabilità del consumatore. Limitare la lunghezza del payload prima della codifica per mantenere la dimensione della matrice — e quindi il lavoro e la dimensione dell’output — entro un budget. Trattare qualsiasi dato decodificato altrove da un barcode come input non attendibile quando rientra nell’applicazione. Consultare il modello delle minacce del motore in /modules/core/security/.

Conformità

Dichiarazione	Standard	Riferimento
I simboli QR Code seguono la specifica della simbologia a matrice QR Code.	ISO/IEC 18004	simbologia QR Code
I simboli Data Matrix seguono la specifica della simbologia Data Matrix.	ISO/IEC 16022	simbologia Data Matrix
I simboli PDF417 seguono la specifica della simbologia PDF417.	ISO/IEC 15438	simbologia PDF417
I simboli Code 128 seguono la specifica della simbologia lineare Code 128.	ISO/IEC 15417	simbologia Code 128
I simboli EAN/UPC seguono la specifica della simbologia EAN/UPC.	ISO/IEC 15420	simbologia EAN/UPC

Questi standard di simbologia non sono presenti nel corpus di citazioni verificabile, quindi non viene registrato alcun reference_id. Il motore parafrasa il requisito e cita la fonte per numero e clausola. Consultare gli standard pubblicati per le regole di codifica autorevoli. Gli encoder sono esercitati da tests/Unit/Barcode/. La correttezza rispetto alle specifiche delle simbologie è responsabilità della test suite, non costituisce un’affermazione di conformità PDF end-to-end.

Vedere anche

• Contratti / Barcode — le interfacce di encoder che queste classi implementano (l’SPI).
• Modulo Graphics — il livello di disegno che traccia la matrice codificata.
• Modulo Document — la facade di alto livello write1DBarcode() / write2DBarcode().
• Panoramica della conformità
• Modello di sicurezza del motore