Pro edição

Barcode — Referência Profunda

Visão geral

A superfície de código de barras do NextPDF Pro adiciona simbologias 2D especializadas e de cadeia de suprimentos sobre o módulo barcode do Core. Ela fornece seis codificadores 2D resolvidos por registro (Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), um codificador de componente 2D GS1 Composite (CC-C), o codificador 1D USPS Intelligent Mail e um parser de GS1 Application Identifier além de um validador de cadeia de suprimentos. A codificação é determinística: o mesmo payload e as mesmas opções sempre produzem uma matriz de módulos idêntica. Esta página declara a API pública, o contrato de comportamento, os modos de falha e as evidências de conformidade por simbologia.

Disponibilidade e licenciamento

Esta capacidade é fornecida no NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença de nível Pro. Uma implantação sem essa habilitação não carrega as classes da capacidade. Compare edições e obtenha uma licença.

composer require nextpdf/pro:^3

Cada simbologia vincula seu próprio nome de capacidade no envelope de licença: barcode.microqr, barcode.dotcode, barcode.hanxin, barcode.jabcode, barcode.rmqr, barcode.gs1databar e barcode.gs1-composite-cc-c. Quando uma capacidade não está licenciada, o registro não resolve aquele codificador. A codificação de símbolo completo do GS1 Composite CC-A e CC-B não é suportada (consulte a tabela de status de suporte), então nenhuma chave barcode.gs1-composite-cc-a ou barcode.gs1-composite-cc-b é registrada.

Superfície pública da API

As chaves de registro vêm dos valores de case do Core NextPDF\Barcode\Barcode2DType mais a chave literal gs1-composite-cc-c. Para codificadores resolvidos por registro, a chave do registro é o contrato estável, não o FQCN do codificador.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`BarcodeProServiceProvider::register()`	`BarcodeEncoderRegistry $registry`	Vincula todas as sete chaves de registro do Pro	`void`	—	Estático; idempotente — uma segunda chamada substitui o primeiro vínculo
`MicroQrEncoder::encode()`	`$data`; opções `ecLevel` (`'L'`, `'M'`, `'Q'`; padrão `'L'`), `version` (1–4 ou null), `mask` (0–3 ou null)	Seleciona automaticamente a menor versão adequada M1–M4	`Barcode2DData`	`InvalidArgumentException`	O `'H'` não suportado é coagido SILENCIOSAMENTE para `'L'` (chamadores que precisam de seleção de EC fail-closed devem pré-validar); M1 ignora `ecLevel`
`DotCodeEncoder::encode()`	`$data`; opções `gs1` (bool, padrão false), `columns` (int), `rows` (int), `ratio` (float, padrão 1.5)	Dimensionamento automático da grade em 1.5 largura:altura	`Barcode2DData`	`InvalidArgumentException`	As dimensões da grade podem ser forçadas por eixo
`HanXinEncoder::encode()`	`$data`; opções `ecLevel` (0–3, padrão 1), `version` (1–84, padrão automático)	Menor versão adequada	`Barcode2DData`	`InvalidArgumentException`	Modos de texto GB 2312 Region 1/2 conforme a ISO/IEC 20830
`JabCodeEncoder::encode()`	`$data`; opções `colors` (4, 8, 16, 32, 64, 128, 256; padrão 8), `eccLevel` (0–10, padrão 3), `symbolNumber` (1–61, padrão 1), `symbolVersions`, `symbolPositions`, `symbolEccLevels`	Símbolo único de 8 cores	`BarcodeColorData`	`InvalidArgumentException`, `JabCodeEncodingException`	Matriz de módulos policromática com paleta
`RmqrEncoder::encode()`	`$data`; opções `ecLevel` (`RmqrConstants::EC_M` padrão, ou `EC_H`), `version` (por exemplo, `'R7x43'`, padrão automático)	Menor ajuste entre as 32 versões da ISO/IEC 23941	`Barcode2DData`	`InvalidArgumentException`	Rejeita payloads que excedem a capacidade; nunca trunca
`Gs1DataBarEncoder::encode()`	`$data`; opções `variant` (`Gs1DataBarVariant`, padrão `OMNIDIRECTIONAL`), `linkage` (bool, padrão false), `height` (int, padrão mínimo da variante; por linha para Expanded Stacked), `segmentsPerRow` (int, padrão 4; apenas Expanded Stacked)	Codifica entrada GTIN (família §5/§6) ou uma string de elemento de AI GS1 (família §7)	`Barcode2DData`	`InvalidArgumentException`; `InvalidSymbolStructureException`	Todas as sete variantes do Annex J da ISO/IEC 24724 codificam
`Gs1DataBarVariant`	—	`isImplemented()` retorna true para todos os sete cases	enum (7 cases)	—	`minimumHeightX()` e `defaultHeightX()` conforme o Annex J
`ImbEncoder::encode()`	`string $code` (20, 25, 29 ou 31 dígitos)	65 barras de quatro estados	`BarcodeData`	`InvalidArgumentException`	Interface de codificador 1D; não é uma chave de registro 2D
`ImbEncoder::encodeToString()`	`string $code`	Estados das barras como uma string T/A/D/F	`string`	`InvalidArgumentException`	Para verificações contra os vetores de referência da USPS
`Gs1DataParser::parse()`	`string $data`	Detecta automaticamente URIs Digital Link, senão o formato `(AI)value`	`Gs1ParsedData`	`InvalidArgumentException`	Implementa o contrato `Gs1DataParserInterface` do Core
`Gs1DataParser::parseDigitalLink()`	`string $uri`	Analisa uma URI GS1 Digital Link	`Gs1ParsedData`	`InvalidArgumentException`	—
`Gs1DataParser::encodeForCode128()` / `::encodeForQrCode()` / `::encodeForDataMatrix()`	`object $parsed`	Sequência de bytes do portador com a convenção FNC1 daquele portador	`string`	—	Espera uma instância de `Gs1ParsedData`
`Gs1DataParser::validateAI()`	`string $ai`, `string $value`	Verificação estrutural de um valor de AI	`bool`	—	—
`Gs1Validator::validate()`	`string $barcodeData`, `Gs1SupplyChainProfile $profile` (padrão `NONE`)	Caminho rápido estático sobre `run()`	`Gs1ValidationResult`	—	Falhas de análise viram achados, não exceções
`Gs1Validator::run()`	igual a `validate()`	Análise, dígitos verificadores, datas, regras entre AIs, perfil	`Gs1ValidationResult`	—	Caminho de instância; o construtor aceita um parser injetado
`Gs1SupplyChainProfile`	—	`NONE` ignora as regras de perfil	enum (5 cases)	—	`RETAIL`, `FOOD`, `PHARMA`, `LOGISTICS`, `NONE`; `requiredAIs()`, `recommendedAIs()`, `primaryIdentifiers()`
`Gs1ValidationResult`	—	Achados particionados por severidade na construção	readonly class	—	`isValid`, `findings`, `errors`, `warnings`, `infos`, `parsedData`; `passes()`, `fails()`, `totalFindings()`
`Gs1ValidationFinding` / `Gs1FindingSeverity`	—	`severity`, `ruleId`, `message`, `ai` e `suggestion` opcionais	readonly class / enum	—	Severidades: `Error`, `Warning`, `Info`
`CompositeComponentA::codewordsFor()`	`string $data`	Codificação de string binária de propósito geral §5, conversão base-928, autoverificação de round-trip	`list<int>` (cada um 0–927)	`InvalidArgumentException`	Alimente `linkFor()` ou um renderizador de portador CC-A externo
`CompositeComponentA::encode()`	ignorado	Recusa a renderização de símbolo completo CC-A	—	`UnsupportedBarcodeFeature` (sempre)	Fail-closed; consulte Casos extremos
`CompositeComponentB::encode()`	ignorado	Recusa a codificação 2D CC-B	—	`UnsupportedBarcodeFeature` (sempre)	`linkFor()` permanece disponível (CCSI 901)
`CompositeComponentC::encode()`	`$data`; opções encaminhadas ao portador PDF417; `carrierType` (padrão `GS1_128`)	Portador PDF417 completo com o codeword CCSI 920 na liderança	`Barcode2DData`	`BarcodeException`; `CompositeLinkageException`	Apenas o portador `GS1_128` é admissível
`CompositeComponent{A,B,C}::linkFor()`	`string $carrierId`, `array $codewords`, `CompositeCarrierType $carrierType`	Emparelha codewords de componente com um portador 1D	`CompositeLinkage`	`CompositeLinkageException`	Impõe admissibilidade e capacidade do portador
`CompositeVariant` / `CompositeCarrierType`	—	`CC_A`, `CC_B`, `CC_C`; `GS1_DATABAR`, `GS1_128`	enums	—	`maxCodewords()`, `ccsi()`, `allowedCarriers()`, `usesFullPdf417()`

Assinaturas dos pontos de entrada

public static function register(BarcodeEncoderRegistry $registry): void

public function encode(string $data, array $options = []): Barcode2DData

public static function validate(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function run(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function parse(string $data): Gs1ParsedData
public function parseDigitalLink(string $uri): Gs1ParsedData
public function encodeForCode128(object $parsed): string
public function encodeForQrCode(object $parsed): string
public function encodeForDataMatrix(object $parsed): string
public function validateAI(string $ai, string $value): bool

public function codewordsFor(string $data): array

Contrato de comportamento

Resolução do registro

A fábrica de registro padrão do Core pré-vincula os codificadores do Pro como entradas preguiçosas (lazy) licenciadas por capacidade. BarcodeProServiceProvider::register() é o fallback suportado para aplicações que compõem um registro sem padrões, por exemplo, integrações de framework com seu próprio container. Cada codificador converte um payload de string e opções por simbologia em um objeto de dados de código de barras que o renderizador de página transforma em operadores de conteúdo PDF.

Análise e validação GS1

O Gs1DataParser aceita strings de AI legíveis por humanos ((01)09521234543213(17)260131) e URIs GS1 Digital Link. Ele produz sequências de bytes codificadas para os portadores GS1-128, QR Code e Data Matrix, aplicando a convenção de FNC1 e de separador de grupo de cada portador. O Gs1Validator executa um pipeline de cinco etapas: análise, dígitos verificadores (GTIN, SSCC), lógica de datas, regras entre AIs e AIs obrigatórias por perfil de setor. Uma falha de análise produz um resultado inválido carregando achados; não lança exceção. Os achados são particionados por severidade em erros, avisos e infos.

Despacho de variantes do GS1 DataBar

O Gs1DataBarEncoder::encode() despacha todas as sete variantes do Annex J da ISO/IEC 24724:2011 por meio de um único contrato de opções. Omnidirectional, Truncated, Stacked e Stacked Omnidirectional compartilham a álgebra de largura de elemento do §5 com um caractere verificador mod-79. Limited usa sua própria álgebra de caractere de símbolo do §6 com um caractere verificador mod-89. Expanded e Expanded Stacked usam a álgebra (17,4) do §7: a máquina de estados de compactação de três modos numérico, alfanumérico e ISO/IEC 646 do §7.2.5.5 mais um caractere verificador mod-211 (§7.2.6). A família §5/§6 recebe um GTIN-14 de 14 dígitos com dígito verificador mod-10 ou uma identificação de item de 13 dígitos. A família §7 recebe uma string de elemento de AI GS1 bruta (dígitos, letras, o subconjunto de pontuação da ISO/IEC 646, FNC1 como o byte 0x1D). A opção linkage define o flag de vínculo de componente 2D para uso como o componente linear de um símbolo GS1 Composite.

Componentes do GS1 Composite

O CC-C produz um componente estendido 2D completo sobre o portador PDF417 completo, injetando o codeword CCSI 920 obrigatório como o codeword de dados líder (ISO/IEC 24723:2010 §5.4). O CC-A gera codewords de dados base-928 conformes por meio de codewordsFor(), com uma autoverificação de round-trip de codificação-decodificação fail-closed, mas recusa a renderização de símbolo completo. O CC-B recusa totalmente a codificação 2D. O linkFor() emparelha codewords de componente com um portador 1D como um valor CompositeLinkage, impondo admissibilidade e capacidade do portador.

Casos extremos e modos de falha

Todo codificador rejeita um payload vazio com InvalidArgumentException.
Micro QR: solicitar o nível de correção de erros H não suportado é coagido SILENCIOSAMENTE para L em vez de falhar (pré-valide as opções se você exigir seleção de EC fail-closed), porque a ISO/IEC 18004 define apenas L, M e Q para símbolos Micro QR.
rMQR: o nível de correção de erros deve ser M ou H; um payload que excede a capacidade das 32 versões é rejeitado, nunca truncado.
JabCode: uma contagem de cores fora do conjunto de potências de dois suportado, um nível de ECC fora de 0–10 ou uma contagem de símbolos fora de 1–61 é rejeitada; falhas de codificação a jusante lançam JabCodeEncodingException.
GS1 DataBar: a família §5/§6 valida o dígito verificador mod-10 do GTIN, e Limited restringe o dígito indicador a 0 ou 1. A família §7 rejeita caracteres não codificáveis e separadores FNC1 finais ou duplicados. Expanded Stacked rejeita uma contagem ímpar de caracteres de símbolo por linha e alturas por linha abaixo do mínimo de 34X. As autoverificações de estrutura interna falham com InvalidSymbolStructureException em vez de emitir um símbolo malformado.
GS1 Composite: encode() de CC-A e CC-B sempre lança UnsupportedBarcodeFeature (fail closed). CC-C lança BarcodeException em dados vazios ou estouro de capacidade do PDF417 (mais de 925 codewords), e CompositeLinkageException para um portador inadmissível.
A validação GS1 sinaliza estrutura de AI malformada e dígitos verificadores incorretos antes da codificação; uma string de cadeia de suprimentos inválida nunca produz um símbolo conforme escaneável.
O IMB aceita apenas entradas de 20, 25, 29 ou 31 dígitos.
A codificação de código de barras não realiza nenhuma criptografia. Não há comportamento específico de modo FIPS; os codificadores são executados de forma idêntica independentemente do perfil FIPS.

Conformidade

O NextPDF implementa essas simbologias em relação aos padrões publicados citados abaixo e fixa traces de referência em seu conjunto de testes. As declarações nesta página são afirmações de capacidade: suporte não é conformidade, e conformidade não é certificação. O NextPDF não possui nenhuma certificação de simbologia. As âncoras de cláusula são parafraseadas a partir do código-fonte do produto e de suas fixtures de conformidade; o corpus do compliance-engine não cobre os padrões de simbologia de código de barras, então as âncoras abaixo são fundamentadas no produto sem identificadores de referência.

Superfície	Norma	Âncora de cláusula (parafraseada)
Álgebra de largura de elemento do GS1 DataBar	ISO/IEC 24724:2011	§5.2 estrutura de caractere de símbolo; Annex F.1 exemplo trabalhado (Omnidirectional); Annex F.2 (Limited); Annex F.3 (Expanded)
Layouts stacked do GS1 DataBar	ISO/IEC 24724:2011	§5.4 Stacked; §5.5 Stacked Omnidirectional; §7.2.8 partição de linhas e separadores do Expanded Stacked
Codificação do GS1 DataBar Expanded	ISO/IEC 24724:2011	§7.2.5.5 máquina de estados de compactação de três modos; §7.2.6 caractere verificador mod-211
Vínculo do GS1 Composite e CC-C	ISO/IEC 24723:2010	§5.4 semântica do codeword CCSI; §5.1 admissibilidade do portador
Codewords do GS1 Composite CC-A	ISO/IEC 24723:2010	§5 codificação de string binária de propósito geral com conversão base-928
Estrutura de símbolo rMQR	ISO/IEC 23941:2022	§6.3.2 Table 1 dimensões de versão; §7.8.2 máscara fixa; referência de format-information do Annex C / Annex I
Micro QR	ISO/IEC 18004	capacidade e format information M1–M4 do Micro QR
Han Xin Code	ISO/IEC 20830:2021	Estrutura de símbolo; padrões de finder e alignment; modos GB 2312 Region 1/2; ECC Reed–Solomon; mascaramento
JabCode	ISO/IEC 23634	Estrutura de símbolo, cor e ECC
Simbologia postal	USPS-B-3200	Estrutura de campo do Intelligent Mail Barcode

Status de suporte por simbologia

Uma variante é Verified quando uma fixture em pro/tests/** a exercita, preferencialmente um reference trace fixado a um exemplo trabalhado publicado. Uma variante fornecida sem fixture dedicada permanece Claimed. Uma variante sem codificador é Not supported.

Simbologia / variante	Status	Evidência (caminho de teste)	Notas
Micro QR (M1–M4)	Verified	`pro/tests/Unit/Barcode/MicroQrEncoderTest.php`	Em nível de unidade; uma fixture de reference-trace de exemplo trabalhado é um backfill rastreado
DotCode	Verified	`pro/tests/Unit/Barcode/DotCodeEncoderTest.php`; `DotCodeGfArithmeticTest.php`	Aritmética de campo de Galois coberta; sem round trip com decodificador de fornecedor
Han Xin Code	Verified	`pro/tests/Unit/Barcode/HanXinEncoderTest.php`; `HanXinRsEncodingTest.php`	Caminho de codificação Reed–Solomon explicitamente exercitado
JabCode (1–61 símbolos, 4–256 cores, ECC 0–10)	Verified	`pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php` (+ 11 conjuntos de componentes no mesmo diretório)	Cascata de múltiplos símbolos e faixa de ECC exercitadas; sem round trip com decodificador de fornecedor
USPS Intelligent Mail Barcode	Verified	`pro/tests/Unit/Barcode/ImbEncoderTest.php`; `ImbRoutingCodeTest.php`	Validação de routing-code e de comprimento de 20/25/29/31 dígitos exercitada
rMQR — todas as 32 versões da ISO/IEC 23941	Verified	`pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php`; `RmqrAnnexCFormatInfoTest.php`; `pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php`	Pares de versão e EC verificados contra a ISO/IEC 23941 Table 1; valores de referência de format-information do Annex C / Annex I
GS1 DataBar — Omnidirectional / Truncated	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php`	Byte a byte igual ao exemplo trabalhado do Annex F.1; Truncated compartilha a codificação com altura reduzida
GS1 DataBar — Stacked / Stacked Omnidirectional	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php`	Divisão de linhas derivada do trace do Annex F.1; construção de separador conforme §5.4 e §5.5
GS1 DataBar — Limited	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php`; `pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php`	Byte a byte igual ao exemplo trabalhado do Annex F.2 (item 00098765432105)
GS1 DataBar — Expanded	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php`; `pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php`	Byte a byte igual ao exemplo trabalhado do Annex F.3 (`(10)12A`); round trip com decodificador independente contra zxing-cpp e ZBar
GS1 DataBar — Expanded Stacked	Verified	`pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php` (casos stacked); o round trip de integração acima	Mesmo pipeline de dados que o Expanded de linha única; partição de linhas e separadores do §7.2.8 afirmados
GS1 Composite — CC-C (portador PDF417)	Verified	`pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php`; `CompositeRoundtripTest.php`; `CompositeLinkageTest.php`	Codeword CCSI 920 e interação do flag de vínculo cobertos
GS1 Composite — CC-A	Partial	`pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php`; `pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php`	Geração de codewords Verified (base-928, autoverificação de round-trip); renderização de símbolo completo não suportada — `encode()` falha de forma segura (fail closed)
GS1 Composite — CC-B	Not supported	`pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php` (afirma a rejeição fail-closed)	Sem codificação 2D; o auxiliar de vínculo (CCSI 901) permanece disponível
Parser de AI GS1	Verified	`pro/tests/Unit/Barcode/Gs1DataParserTest.php`; `Gs1DataParserFnc1Test.php`	Ambos os formatos de entrada e todas as três saídas de sequência de bytes por portador exercitadas
Validador de cadeia de suprimentos GS1	Verified	`pro/tests/Unit/Barcode/Gs1ValidatorTest.php`; `Gs1ValidatorCrossAiTest.php`; `pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php`	Dígitos verificadores, combinações obrigatórias entre AIs e lógica de datas exercitados

Notas de desenvolvimento

As âncoras de evidência nesta página são caminhos de teste em pro/tests/**; o repositório não fornece nenhum diretório examples/ para este módulo.
Os sete nomes de capacidade listados em Disponibilidade e licenciamento são as chaves que o service provider vincula. O codificador IMB é construído diretamente e não carrega nenhuma chave de registro.
O CC-A emite apenas o método de codificação de propósito geral; os métodos comprimidos específicos de aplicação são um residual de densidade documentado, não uma lacuna de correção.

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 mecanismo, nomes de arquivo de runbook e prefixos de ticket estão fora de escopo.