Contracts / Barcode

Visão geral

O domínio de código de barras define quatro contratos: um codificador unidimensional (1D), um codificador bidimensional (2D), um codificador genérico descoberto pelo registro e um parser de dados GS1. Juntos, eles definem o formato que os serviços de código de barras devem atender. As implementações das simbologias são registradas com base nesses contratos.

Instalação

composer require nextpdf/core:^3

Visão conceitual

Um codificador de código de barras transforma uma string de payload na matriz de módulos que o escritor de Portable Document Format (PDF) desenha. O NextPDF separa os contratos de codificador por dimensionalidade. A Barcode1DEncoderInterface lida com simbologias lineares, como Code 128 e EAN-13, e retorna um value object BarcodeData. A Barcode2DEncoderInterface lida com simbologias de matriz, como Quick Response (QR) Code e Data Matrix. Ela retorna um value object Barcode2DData com um mapa de opções para configurações específicas da simbologia, como o nível de correção de erros.

BarcodeEncoderInterface é o contrato genérico de provedor de serviço. Qualquer codificador 2D descoberto pela BarcodeEncoderRegistry implementa esse contrato. O contrato retorna uma matriz monocromática Barcode2DData ou uma matriz colorida BarcodeColorData, permitindo que um codificador registrado produza um símbolo colorido sem uma interface separada. Espera-se que os codificadores sejam stateless, exceto pela configuração feita no momento da construção. O registro retorna uma única instância compartilhada por tipo registrado; portanto, qualquer estado por chamada seria um defeito.

Gs1DataParserInterface é o contrato de dados estruturados. Ele faz o parsing de uma element string GS1 em um objeto tipado e, em seguida, recodifica esse objeto para um portador QR Code, Data Matrix ou Code 128. Isso mantém a gramática GS1 separada da simbologia. O parser valida os Application Identifiers uma única vez. Os métodos específicos de cada portador formatam a mesma estrutura analisada para cada destino. Os quatro contratos são stable. A BarcodeEncoderInterface é stable desde 3.0.0; os demais desde 1.0.0. Novos métodos só são adicionados com implementações padrão.

Superfície da API

Tipo	Categoria	Membros principais	Estabilidade	Desde
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

Nos contratos 2D, o array $options é específico de cada simbologia, como o nível de correção de erros para QR Code. O contrato não restringe as chaves desse array. Cada codificador registrado documenta seu próprio conjunto de opções.

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

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() e write2DBarcode() resolvem um codificador por meio do registro. O código da aplicação raramente acessa os contratos diretamente. Você especifica uma simbologia, e o registro fornece o codificador.

Exemplo de código — Produção

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

O serviço depende dos contratos de parser e de codificador. O bloco catch registra e relança a BarcodeException específica; ele nunca captura uma \Exception genérica.

Casos extremos e armadilhas

• Um codificador registrado é compartilhado. Estado por chamada em um codificador corrompe renderizações concorrentes. Mantenha os codificadores stateless, exceto pela configuração feita no construtor.
• BarcodeEncoderInterface::encode() pode retornar dados coloridos ou monocromáticos. O código que o consome deve tratar tanto Barcode2DData quanto BarcodeColorData, sem presumir monocromático.
• O array $options 2D não é validado pelo contrato. A maioria dos codificadores ignora silenciosamente chaves desconhecidas. Verifique o nome da chave na documentação do próprio codificador.
• O parsing GS1 é rigoroso quanto à gramática. Uma element string com um Application Identifier desconhecido lança uma BarcodeException em vez de produzir um parse parcial. Valide a entrada na origem.
• Os contratos 1D e 2D não são intercambiáveis. Passar um payload de QR para um codificador 1D produz um símbolo inválido. O registro roteia pelo tipo de simbologia; portanto, prefira o registro a uma chamada direta de contrato.

Desempenho

O custo de codificação escala com o comprimento do payload e o tamanho da matriz de destino, não com o contrato que você chama. Um payload Code 128 curto é codificado em microssegundos. Um QR Code denso, com alta correção de erros, é o caso 2D mais pesado. Ainda assim, ele fica bem dentro do performance_budget de 1500 ms de tempo total e 64 MB de pico para a página de exemplo com múltiplos símbolos. A matriz é calculada uma única vez e desenhada como operadores PDF. A reprodutibilidade é bitwise porque o mesmo payload e as mesmas opções sempre produzem a mesma matriz de módulos. A consulta ao registro é O(1). O algoritmo de simbologia faz o trabalho.

Notas de segurança

Payloads de código de barras muitas vezes podem ser influenciados por atacantes, como um Uniform Resource Locator (URL) escaneado, um número de série ou um código de rastreamento. Os contratos codificam bytes; eles não os interpretam. Um QR Code que codifica uma URL hostil continua sendo um QR Code válido; portanto, a confiança no payload é responsabilidade do consumidor, não do codificador. Restrinja o comprimento do payload antes de codificar para limitar o tamanho da matriz e evitar uma negação de serviço causada por um símbolo grande demais. O parser GS1 rejeita Application Identifiers malformados, o que remove uma superfície de injeção. Ele não valida o conteúdo semântico de campos válidos. Trate os dados de código de barras decodificados como entrada não confiável sempre que eles reentrarem na aplicação.

Conformidade

Afirmação	Norma	Referência
Os símbolos QR Code seguem a especificação de simbologia de matriz 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 Code 128 seguem a especificação de simbologia linear do Code 128.	ISO/IEC 15417	Simbologia Code 128
As element strings GS1 são analisadas conforme a gramática de Application Identifier do GS1.	GS1 General Specifications	Application Identifiers

Essas normas são referenciadas por número e cláusula. Elas não estão presentes no corpus de citações verificáveis; portanto, nenhum reference_id é registrado. O motor parafraseia o requisito e cita a fonte. Consulte as normas publicadas para obter as regras oficiais de codificação.

Contexto comercial

O Core define e congela os contratos de codificador e fornece as simbologias comuns. As edições Pro e Enterprise registram um conjunto estendido de codificadores para simbologias de código de barras adicionais sob a mesma BarcodeEncoderInterface, de modo que uma implantação comercial ganha cobertura sem alterar a interface de programação de aplicações (API). O Core resolve os codificadores registrados por meio da BarcodeEncoderRegistry. A superfície de contrato é idêntica entre as edições.

Veja também

• Contracts: 41 interfaces públicas (SPI) — visão geral da interface de provedor de serviço (SPI) e dos níveis de estabilidade.
• Barcode — implementações de simbologia registradas com base nesses contratos.
• Contracts / Document — a PdfDocumentInterface que pinta a matriz codificada.
• Graphics — camada de desenho que renderiza os módulos do código de barras.
• Exception — BarcodeException lançada em entrada GS1 malformada.