Barcode: codificadores de simbologias 1D e 2D

Visão geral

O módulo Barcode fornece a camada de implementação das simbologias. Ele codifica simbologias lineares (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, códigos postais) e simbologias matriciais (QR Code, Data Matrix, PDF417). Também calcula a correção de erro e registra cada codificador por trás dos contratos de barcode, para que o gravador do documento possa pintar o resultado. As definições dos contratos ficam em uma página separada. Veja a nota abaixo.

Uma página canônica por assunto. As interfaces que um codificador satisfaz (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) estão documentadas em Contracts / Barcode. Esta página documenta os codificadores concretos que implementam esses contratos. As páginas são complementares, não duplicadas. Leia a página de contratos para a interface de provedor de serviço (SPI). Leia esta página para entender as simbologias.

Instalação

composer require nextpdf/core:^3

Visão conceitual

Um codificador de barcode transforma uma string de payload em uma matriz de módulos bidimensional (2D) ou em uma sequência de barras unidimensional (1D), que o gravador pinta como gráficos em Portable Document Format (PDF). Este módulo fornece os codificadores concretos.

Barcode1D é o motor linear. BarcodeType enumera as simbologias lineares suportadas: Code 39 (com e sem checksum), Code 93, a família 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() retorna um objeto de valor BarcodeData que descreve o padrão de barras.

Os codificadores 2D, QrEncoder, DataMatrixEncoder e Pdf417Encoder, implementam BarcodeEncoderInterface e retornam uma matriz Barcode2DData. Barcode2DType enumera as simbologias matriciais que o motor reconhece, incluindo QR Code, Data Matrix e PDF417. Simbologias adicionais, como Micro QR, rMQR, GS1 DataBar e Han Xin, são enumeradas para o roteamento do registry. O conjunto de codificadores que oferece suporte a cada simbologia depende da edição. A correção de erro matricial é calculada sobre um corpo de Galois. GaloisField e GaloisFieldPrime fornecem a aritmética Reed-Solomon compartilhada pelos codificadores QR, Data Matrix e PDF417.

BarcodeEncoderRegistry é o mecanismo de resolução. Ele implementa a PHP Standards Recommendation 11 (PSR-11) ContainerInterface, fornece o registro padrão por meio de createDefault() e resolve uma simbologia para seu codificador com resolve(). O código da aplicação raramente acessa um codificador diretamente. A fachada de alto nível Document::write1DBarcode() / write2DBarcode() informa uma simbologia, e o registry fornece o codificador. O motor 1D é @since 1.0.0. Os codificadores 2D são @since 1.3.0. O registry é @since 3.0.0.

Superfície da API

Classe	Membros principais	Função
Barcode1D	generate(string $code, BarcodeType $type): BarcodeData	Codificador de simbologia linear (@since 1.0.0)
QrEncoder	encode(string $data, array $options = []): Barcode2DData	Codificador de QR Code (@since 1.3.0)
DataMatrixEncoder	encode(string $data, array $options = []): Barcode2DData	Codificador de Data Matrix (@since 1.3.0)
Pdf417Encoder	encode(string $data, array $options = []): Barcode2DData	Codificador de PDF417 (@since 1.3.0)
BarcodeEncoderRegistry	createDefault(), register(), resolve(), has(), get(), registered()	Registry de codificadores PSR-11 (@since 3.0.0)
BarcodeType / Barcode2DType	casos de enum	Enumerações de simbologias suportadas
GaloisField / GaloisFieldPrime	aritmética de corpo finito	Correção de erro Reed-Solomon

Execute composer docs:generate-api-php -- --module=Barcode para gerar a tabela completa de PHPDoc.

Exemplo de código — Início rápido

Fonte: examples/10-barcodes.php. A fachada resolve o codificador para a simbologia solicitada por meio do registry.

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

Exemplo de código — Produção

Resolva um codificador 2D diretamente pelo registry e limite o payload antes de codificar.

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

Casos extremos & pegadinhas

• Um payload linear que viola o conjunto de caracteres de uma simbologia ou a regra de dígito verificador lança BarcodeException. EAN/UPC calculam e anexam o dígito verificador. Não o anexe antecipadamente.
• O array $options para 2D é específico de cada simbologia, como um nível de correção de erro para QR. A maioria dos codificadores ignora chaves desconhecidas. Verifique cada chave na documentação do próprio codificador.
• Barcode2DType enumera mais simbologias do que a edição core fornece codificadores. BarcodeEncoderRegistry::resolve() lança uma exceção para uma simbologia não registrada em vez de retornar um placeholder.
• Os codificadores registrados são instâncias compartilhadas. Mantenha-os sem estado além da configuração do construtor. Estado por chamada corrompe renderizações concorrentes.
• Um payload longo demais produz uma matriz mais densa e maior. Limite o comprimento do payload antes de codificar para evitar negação de serviço por meio do tamanho do símbolo.

Desempenho

O custo de codificação escala com o comprimento do payload e o tamanho da matriz, não com a busca no registry, que é O(1). Um payload curto de Code 128 é codificado em microssegundos. Um QR Code denso com alta correção de erro é o caso mais pesado. A página de exemplo com múltiplos símbolos permanece dentro do orçamento de 1500 ms de wall / 64 MB de pico. O perfil de reprodutibilidade é bitwise. O mesmo payload e as mesmas opções sempre produzem a mesma matriz de módulos e os mesmos bytes desenhados.

Notas de segurança

Os payloads de barcode muitas vezes vêm de fontes não confiáveis: um uniform resource locator (URL) escaneado, um número de série ou um código de rastreamento. Os codificadores codificam bytes; não os interpretam. Um QR Code que codifica uma URL hostil continua sendo um QR Code válido, portanto o consumidor é responsável pela confiança no payload. Limite o comprimento do payload antes de codificar para manter o tamanho da matriz, o trabalho e o tamanho da saída dentro de um orçamento. Trate como entrada não confiável quaisquer dados decodificados de um barcode em outro ponto quando eles voltarem à aplicação. Veja o modelo de ameaças do motor em /modules/core/security/.

Conformidade

Afirmação	Padrão	Referência
Os símbolos QR Code seguem a especificação de simbologia matricial do QR Code.	ISO/IEC 18004	Simbologia QR Code
Os símbolos Data Matrix seguem a especificação de simbologia do Data Matrix.	ISO/IEC 16022	Simbologia Data Matrix
Os símbolos PDF417 seguem a especificação de simbologia do PDF417.	ISO/IEC 15438	Simbologia PDF417
Os símbolos Code 128 seguem a especificação de simbologia linear do Code 128.	ISO/IEC 15417	Simbologia Code 128
Os símbolos EAN/UPC seguem a especificação de simbologia do EAN/UPC.	ISO/IEC 15420	Simbologia EAN/UPC

Esses padrões de simbologia não estão presentes no corpus de citações verificáveis, portanto nenhum reference_id é registrado. Esta página parafraseia o requisito e cita a fonte por número e cláusula. Consulte os padrões publicados para conhecer as regras de codificação autoritativas. Os codificadores são exercitados por tests/Unit/Barcode/. A correção em relação às especificações de simbologia é responsabilidade da suíte de testes, não uma declaração de conformidade PDF de ponta a ponta.

Veja também

• Contracts / Barcode — as interfaces de codificador que essas classes implementam (a SPI).
• Módulo Graphics — a camada de desenho que pinta a matriz codificada.
• Módulo Document — a fachada de alto nível write1DBarcode() / write2DBarcode().
• Visão geral de conformidade
• Modelo de segurança do motor