Barcode

Visão geral

O NextPDF Pro acrescenta simbologias de código de barras 2D especializadas e de cadeia de suprimentos sobre as simbologias linear e QR da edição open source. Cada simbologia é renderizada diretamente em uma superfície de página PDF como um content stream determinístico.

Disponibilidade e licenciamento

Este recurso é fornecido no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem essa titularidade não carrega as classes do recurso. Compare as edições e obtenha uma licença.

Instalação

composer require nextpdf/pro:^3

Os codificadores do Pro se registram por meio do registro padrão de codificadores de código de barras. Aplicativos que constroem seu próprio registro podem reregistrar os codificadores do Pro explicitamente por meio do service provider publicado.

Visão conceitual

A edição open source cobre as simbologias linear e QR do dia a dia. O NextPDF Pro estende o mesmo registro com simbologias especializadas para uso em varejo, logística, postal e industrial de alta densidade:

• Micro QR Code — a variante compacta de QR para pouco espaço de rótulo.
• DotCode — uma simbologia de matriz de pontos projetada para marcação industrial de alta velocidade.
• Han Xin Code — uma simbologia 2D com capacidade nativa de texto CJK de grande conjunto, conforme ISO/IEC 20830.
• JabCode — uma simbologia 2D policromática com cascateamento de múltiplos símbolos.
• rMQR — a variante retangular do Micro QR para rótulos estreitos e largos.
• GS1 DataBar — a família de simbologias GS1 de varejo e cupom.
• GS1 Composite (CC-C) — uma base 1D vinculada mais um componente de extensão 2D PDF417 de alta densidade que carrega dados de GS1 Application Identifier. (A codificação de componente estendido 2D CC-A e CC-B não é suportada nesta versão; consulte a matriz de suporte.)

Cada codificador produz um objeto de dados de código de barras que o renderizador de página converte em operadores de conteúdo PDF. A codificação é determinística: a mesma entrada e as mesmas opções sempre produzem o mesmo padrão de módulos, o que mantém documentos assinados e arquivados reproduzíveis.

A referência profunda de código de barras carrega uma matriz de suporte por simbologia com evidências. Para cada simbologia e variante, a matriz registra um de três estados: uma fixture de conformidade no repositório a exercita (Verified), a superfície de implementação a afirma sem uma fixture dedicada (Claimed) ou ela fica fora do escopo (Not supported). O NextPDF relata a matriz com honestidade: uma variante que fornece um codificador, mas carece de uma fixture de rastreamento de referência permanece Claimed com uma nota de backfill, em vez de superdeclarada.

Por que funciona assim

Cada codificador do Pro é uma função pura: o mesmo payload e as mesmas opções sempre produzem a mesma matriz de módulos, sem estado oculto ou aleatoriedade semeada. Esse determinismo é a decisão de sustentação. Ele permite que um código de barras faça o round-trip por um documento assinado ou arquivado sem perturbar o fluxo de bytes, de modo que uma re-renderização nunca invalida uma assinatura. Ele também torna a conformidade auditável: a matriz de suporte fixa cada simbologia a um rastreamento de referência armazenado, verificado bit a bit contra um golden file. Estender o BarcodeEncoderRegistry do Core em vez de fazer um fork dele mantém essas garantias idênticas entre as edições open e Pro.

Contexto de design: Os mesmos bytes toda vez: PDFs reproduzíveis.

Superfície da API

composer require nextpdf/pro:^3

A superfície pública de código de barras do Pro consiste em:

• Um ponto de entrada estático de service provider que registra os codificadores 2D do Pro em um registro de codificadores de código de barras (MicroQR, DotCode, HanXin, JabCode, RMQR, GS1DataBar e a chave de componente GS1 Composite CC-C gs1-composite-cc-c). A codificação de componente estendido 2D GS1 Composite CC-A e CC-B não é suportada nesta versão e não é registrada.
• Um parser de GS1 Application Identifier que aceita tanto strings de AI legíveis por humanos quanto URIs de GS1 Digital Link e produz sequências de bytes codificadas para portadores GS1-128, QR Code e Data Matrix.
• Um validador de cadeia de suprimentos GS1 que verifica dígitos verificadores, estrutura de AI, lógica de datas e combinações obrigatórias de AI do perfil do setor.

A tabela completa de assinaturas de método gerada é renderizada na referência profunda de código de barras.

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

use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Pro\Barcode\BarcodeProServiceProvider;

$registry = new BarcodeEncoderRegistry();
BarcodeProServiceProvider::register($registry);
// $registry now resolves the Pro specialty symbologies.

Exemplo de código — Produção

use NextPDF\Pro\Barcode\Gs1\Gs1Validator;
use NextPDF\Pro\Barcode\Gs1\Gs1SupplyChainProfile;

$result = Gs1Validator::validate(
    '(01)09521234543213(17)260131(10)ABC123',
    Gs1SupplyChainProfile::NONE,
);

if (! $result->isValid) {
    // Surface findings to your observability pipeline before encoding.
    foreach ($result->findings as $finding) {
        $logger->warning('GS1 validation finding', [
            'rule' => $finding->ruleId,
            'detail' => $finding->message,
        ]);
    }
}

Casos extremos e armadilhas

• O registro padrão pré-vincula as entradas de codificador do Pro preguiçosamente e as restringe por meio do registro de capacidades. Uma chamada explícita a BarcodeProServiceProvider::register() é o fallback suportado quando um aplicativo compõe seu próprio registro sem padrões.
• O reregistro é idempotente: uma segunda chamada a register() substitui a primeira vinculação em vez de lançar erro.
• A cobertura de variantes do GS1 DataBar é parcial por design. Omnidirectional, Truncated, Stacked, Stacked Omnidirectional e Limited são verificadas por referência; Expanded e Expanded Stacked estão fora do escopo nesta versão. Consulte a matriz de suporte.
• O rMQR aceita toda versão ISO 23941 por meio da suíte de conformidade validada pelo Annex. Metadados de rastreamento de escopo anteriores à expansão posterior da faixa de tamanhos podem subestimar isso; a matriz de suporte registra a realidade verificada por código.

Desempenho

O custo de codificação escala com o comprimento do payload e o tamanho do símbolo de destino. Cada simbologia dispõe seu símbolo em uma única passagem sem reflow. Os cascateamentos de múltiplos símbolos do JabCode escalam com a contagem de símbolos (1–61). A codificação mantém a matriz de módulos em memória; a maior versão de símbolo selecionada delimita o custo.

Notas de segurança

Os codificadores de código de barras não executam o conteúdo do payload; eles o codificam como dados. A validação GS1 rejeita estruturas de AI malformadas e dígitos verificadores inválidos antes da codificação, o que impede que uma string de cadeia de suprimentos malformada produza um símbolo escaneável mas não conforme. Os codificadores não registram nenhum payload por si só; os aplicativos devem limpar payloads sensíveis de seus próprios logs.

Conformidade

Cada simbologia segue seu padrão publicado relevante (ISO/IEC 24724 para GS1 DataBar, ISO/IEC 24723 para GS1 Composite, ISO/IEC 23941 para rMQR, ISO/IEC 18004 Annex para Micro QR, ISO/IEC 20830 para Han Xin Code, ISO/IEC 23634 para JabCode, USPS-B-3200 para a simbologia postal). O mapeamento de conformidade no nível de cláusula com identificadores de citação é renderizado na referência profunda de código de barras.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora do escopo.

Consulte também

• Módulo de código de barras do Core
• Chart — NextPDF Pro
• Referência profunda de código de barras