Códigos de barras — Referencia detallada

De un vistazo

La superficie de códigos de barras de NextPDF Pro añade simbologías 2D especializadas y de cadena de suministro sobre el módulo de códigos de barras de Core. Incluye seis codificadores 2D resueltos por registro (Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), un codificador de componente 2D GS1 Composite (CC-C), el codificador 1D USPS Intelligent Mail y un analizador de identificadores de aplicación GS1 más un validador de cadena de suministro. La codificación es determinista: la misma carga útil y las mismas opciones producen siempre una matriz de módulos idéntica. Esta página detalla la API pública, el contrato de comportamiento, los modos de fallo y la evidencia de conformidad por simbología.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Compare ediciones y obtenga una licencia.

composer require nextpdf/pro:^3

Cada simbología vincula su propio nombre de capacidad en el sobre de licencia: barcode.microqr, barcode.dotcode, barcode.hanxin, barcode.jabcode, barcode.rmqr, barcode.gs1databar y barcode.gs1-composite-cc-c. Cuando una capacidad no está licenciada, el registro no resuelve ese codificador. La codificación de símbolo completo GS1 Composite CC-A y CC-B no es compatible (véase la tabla de estado de soporte), por lo que no se registra ninguna clave barcode.gs1-composite-cc-a ni barcode.gs1-composite-cc-b.

Superficie de la API pública

Las claves de registro provienen de los valores de caso de NextPDF\Barcode\Barcode2DType de Core más la clave literal gs1-composite-cc-c. Para los codificadores resueltos por registro, la clave de registro es el contrato estable, no el FQCN del codificador.

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
BarcodeProServiceProvider::register()	BarcodeEncoderRegistry $registry	Vincula las siete claves de registro de Pro	void	—	Estático; idempotente: una segunda llamada reemplaza la primera vinculación
MicroQrEncoder::encode()	$data; opciones ecLevel ('L', 'M', 'Q'; por defecto 'L'), version (1–4 o null), mask (0–3 o null)	Selecciona automáticamente la versión más pequeña que ajusta M1–M4	Barcode2DData	InvalidArgumentException	El 'H' no compatible se convierte SILENCIOSAMENTE a 'L' (quienes necesiten selección de EC a prueba de fallos deben prevalidar); M1 ignora ecLevel
DotCodeEncoder::encode()	$data; opciones gs1 (bool, por defecto false), columns (int), rows (int), ratio (float, por defecto 1.5)	Dimensionado automático de rejilla a 1.5 ancho:alto	Barcode2DData	InvalidArgumentException	Las dimensiones de la rejilla pueden forzarse por eje
HanXinEncoder::encode()	$data; opciones ecLevel (0–3, por defecto 1), version (1–84, por defecto automática)	Versión más pequeña que ajusta	Barcode2DData	InvalidArgumentException	Modos de texto GB 2312 Región 1/2 según ISO/IEC 20830
JabCodeEncoder::encode()	$data; opciones colors (4, 8, 16, 32, 64, 128, 256; por defecto 8), eccLevel (0–10, por defecto 3), symbolNumber (1–61, por defecto 1), symbolVersions, symbolPositions, symbolEccLevels	Símbolo único de 8 colores	BarcodeColorData	InvalidArgumentException, JabCodeEncodingException	Matriz de módulos policroma con paleta
RmqrEncoder::encode()	$data; opciones ecLevel (RmqrConstants::EC_M por defecto, o EC_H), version (p. ej. 'R7x43', por defecto automática)	La más pequeña que ajusta de las 32 versiones ISO/IEC 23941	Barcode2DData	InvalidArgumentException	Rechaza cargas útiles que exceden la capacidad; nunca trunca
Gs1DataBarEncoder::encode()	$data; opciones variant (Gs1DataBarVariant, por defecto OMNIDIRECTIONAL), linkage (bool, por defecto false), height (int, por defecto el mínimo de la variante; por fila para Expanded Stacked), segmentsPerRow (int, por defecto 4; solo Expanded Stacked)	Codifica una entrada GTIN (familia §5/§6) o una cadena de elementos de IA GS1 (familia §7)	Barcode2DData	InvalidArgumentException; InvalidSymbolStructureException	Se codifican las siete variantes del Anexo J de ISO/IEC 24724
Gs1DataBarVariant	—	isImplemented() devuelve true para los siete casos	enum (7 casos)	—	minimumHeightX() y defaultHeightX() según el Anexo J
ImbEncoder::encode()	string $code (20, 25, 29 o 31 dígitos)	65 barras de cuatro estados	BarcodeData	InvalidArgumentException	Interfaz de codificador 1D; no es una clave de registro 2D
ImbEncoder::encodeToString()	string $code	Estados de barra como cadena T/A/D/F	string	InvalidArgumentException	Para comprobaciones contra vectores de referencia de USPS
Gs1DataParser::parse()	string $data	Detecta automáticamente URIs de Digital Link, si no formato (AI)value	Gs1ParsedData	InvalidArgumentException	Implementa el contrato Gs1DataParserInterface de Core
Gs1DataParser::parseDigitalLink()	string $uri	Analiza una URI de GS1 Digital Link	Gs1ParsedData	InvalidArgumentException	—
Gs1DataParser::encodeForCode128() / ::encodeForQrCode() / ::encodeForDataMatrix()	object $parsed	Secuencia de bytes del portador con la convención FNC1 de ese portador	string	—	Espera una instancia Gs1ParsedData
Gs1DataParser::validateAI()	string $ai, string $value	Comprobación estructural del valor de una IA	bool	—	—
Gs1Validator::validate()	string $barcodeData, Gs1SupplyChainProfile $profile (por defecto NONE)	Ruta rápida estática sobre run()	Gs1ValidationResult	—	Los fallos de análisis se convierten en hallazgos, no en excepciones
Gs1Validator::run()	como validate()	Análisis, dígitos de control, fechas, reglas entre IA, perfil	Gs1ValidationResult	—	Ruta de instancia; el constructor acepta un analizador inyectado
Gs1SupplyChainProfile	—	NONE omite las reglas de perfil	enum (5 casos)	—	RETAIL, FOOD, PHARMA, LOGISTICS, NONE; requiredAIs(), recommendedAIs(), primaryIdentifiers()
Gs1ValidationResult	—	Hallazgos particionados por severidad en la construcción	clase readonly	—	isValid, findings, errors, warnings, infos, parsedData; passes(), fails(), totalFindings()
Gs1ValidationFinding / Gs1FindingSeverity	—	severity, ruleId, message, ai y suggestion opcionales	clase readonly / enum	—	Severidades: Error, Warning, Info
CompositeComponentA::codewordsFor()	string $data	Encodación de cadena binaria de propósito general §5, conversión base-928, autocomprobación de ida y vuelta	list<int> (cada uno 0–927)	InvalidArgumentException	Alimenta linkFor() o un renderizador de portador CC-A externo
CompositeComponentA::encode()	ignorado	Rechaza el renderizado de símbolo completo CC-A	—	UnsupportedBarcodeFeature (siempre)	A prueba de fallos; véase Casos límite
CompositeComponentB::encode()	ignorado	Rechaza la codificación 2D de CC-B	—	UnsupportedBarcodeFeature (siempre)	linkFor() sigue disponible (CCSI 901)
CompositeComponentC::encode()	$data; opciones reenviadas al portador PDF417; carrierType (por defecto GS1_128)	Portador PDF417 completo con la palabra de código CCSI 920 al inicio	Barcode2DData	BarcodeException; CompositeLinkageException	Solo el portador GS1_128 es admisible
CompositeComponent{A,B,C}::linkFor()	string $carrierId, array $codewords, CompositeCarrierType $carrierType	Empareja las palabras de código del componente con un portador 1D	CompositeLinkage	CompositeLinkageException	Aplica la admisibilidad y la capacidad del portador
CompositeVariant / CompositeCarrierType	—	CC_A, CC_B, CC_C; GS1_DATABAR, GS1_128	enums	—	maxCodewords(), ccsi(), allowedCarriers(), usesFullPdf417()

Firmas de los puntos 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 comportamiento

Resolución del registro

La fábrica de registro por defecto de Core previncula los codificadores de Pro como entradas perezosas y con licencia por capacidad. BarcodeProServiceProvider::register() es el recurso de reserva admitido para aplicaciones que componen un registro sin valores por defecto, por ejemplo integraciones de framework con su propio contenedor. Cada codificador convierte una carga útil de cadena y opciones por simbología en un objeto de datos de código de barras que el renderizador de página transforma en operadores de contenido PDF.

Análisis y validación GS1

Gs1DataParser acepta cadenas de IA legibles por humanos ((01)09521234543213(17)260131) y URIs de GS1 Digital Link. Produce secuencias de bytes codificadas para los portadores GS1-128, QR Code y Data Matrix, aplicando la convención de FNC1 y separador de grupo de cada portador. Gs1Validator ejecuta una canalización de cinco pasos: análisis, dígitos de control (GTIN, SSCC), lógica de fechas, reglas entre IA e IA obligatorias del perfil de industria. Un fallo de análisis produce un resultado no válido que porta hallazgos; no lanza. Los hallazgos se particionan por severidad en errores, advertencias e informativos.

Despacho de variantes de GS1 DataBar

Gs1DataBarEncoder::encode() despacha las siete variantes del Anexo J de ISO/IEC 24724:2011 a través de un único contrato de opciones. Omnidirectional, Truncated, Stacked y Stacked Omnidirectional comparten el álgebra de anchura de elemento del §5 con un carácter de control mod-79. Limited usa su propia álgebra de carácter de símbolo del §6 con un carácter de control mod-89. Expanded y Expanded Stacked usan el álgebra (17,4) del §7: la máquina de estados de compactación de tres modos (numérico, alfanumérico e ISO/IEC 646) del §7.2.5.5 más un carácter de control mod-211 (§7.2.6). La familia §5/§6 toma un GTIN-14 de 14 dígitos con dígito de control mod-10 o una identificación de artículo de 13 dígitos. La familia §7 toma una cadena de elementos de IA GS1 en bruto (dígitos, letras, el subconjunto de puntuación ISO/IEC 646, FNC1 como byte 0x1D). La opción linkage establece el indicador de enlace de componente 2D para su uso como componente lineal de un símbolo GS1 Composite.

Componentes GS1 Composite

CC-C produce un componente extendido 2D completo sobre el portador PDF417 completo, inyectando la palabra de código CCSI obligatoria 920 como la palabra de código de datos inicial (ISO/IEC 24723:2010 §5.4). CC-A genera palabras de código de datos base-928 conformes mediante codewordsFor(), con una autocomprobación de ida y vuelta codificar-decodificar a prueba de fallos, pero rechaza el renderizado de símbolo completo. CC-B rechaza por completo la codificación 2D. linkFor() empareja las palabras de código del componente con un portador 1D como un valor CompositeLinkage, aplicando la admisibilidad y la capacidad del portador.

Casos límite y modos de fallo

• Todo codificador rechaza una carga útil vacía con InvalidArgumentException.
• Micro QR: solicitar el nivel de corrección de errores H no compatible se convierte SILENCIOSAMENTE a L en lugar de fallar (prevalide las opciones si requiere una selección de EC a prueba de fallos), porque ISO/IEC 18004 define solo L, M y Q para los símbolos Micro QR.
• rMQR: el nivel de corrección de errores debe ser M o H; una carga útil que excede la capacidad de las 32 versiones se rechaza, nunca se trunca.
• JabCode: un recuento de colores fuera del conjunto de potencias de dos admitido, un nivel de ECC fuera de 0–10 o un recuento de símbolos fuera de 1–61 se rechaza; los fallos de codificación posteriores lanzan JabCodeEncodingException.
• GS1 DataBar: la familia §5/§6 valida el dígito de control mod-10 del GTIN, y Limited restringe el dígito indicador a 0 o 1. La familia §7 rechaza los caracteres no codificables y los separadores FNC1 finales o duplicados. Expanded Stacked rechaza un recuento impar de caracteres de símbolo por fila y las alturas por fila por debajo del mínimo de 34X. Las autocomprobaciones de estructura interna fallan con InvalidSymbolStructureException en lugar de emitir un símbolo malformado.
• GS1 Composite: los encode() de CC-A y CC-B siempre lanzan UnsupportedBarcodeFeature (a prueba de fallos). CC-C lanza BarcodeException con datos vacíos o desbordamiento de capacidad de PDF417 (más de 925 palabras de código), y CompositeLinkageException para un portador inadmisible.
• La validación GS1 marca la estructura de IA malformada y los dígitos de control incorrectos antes de codificar; una cadena de cadena de suministro no válida nunca produce un símbolo conforme escaneable.
• IMB acepta únicamente entradas de 20, 25, 29 o 31 dígitos.
• La codificación de códigos de barras no realiza criptografía. No hay comportamiento específico del modo FIPS; los codificadores se ejecutan de forma idéntica con independencia del perfil FIPS.

Conformidad

NextPDF implementa estas simbologías conforme a las normas publicadas citadas a continuación y fija trazas de referencia en su conjunto de pruebas. Las afirmaciones de esta página son declaraciones de capacidad: el soporte no es conformidad y la conformidad no es certificación. NextPDF no posee ninguna certificación de simbología. Los anclajes de cláusula están parafraseados a partir del código fuente del producto y sus fixtures de conformidad; el corpus del compliance-engine no cubre las normas de simbología de códigos de barras, por lo que los anclajes siguientes están fundamentados en el producto sin identificadores de referencia.

Superficie	Norma	Anclaje de cláusula (parafraseado)
Álgebra de anchura de elemento de GS1 DataBar	ISO/IEC 24724:2011	§5.2 estructura de carácter de símbolo; Anexo F.1 ejemplo resuelto (Omnidirectional); Anexo F.2 (Limited); Anexo F.3 (Expanded)
Disposiciones apiladas de GS1 DataBar	ISO/IEC 24724:2011	§5.4 Stacked; §5.5 Stacked Omnidirectional; §7.2.8 partición de filas y separadores de Expanded Stacked
Encodación Expanded de GS1 DataBar	ISO/IEC 24724:2011	§7.2.5.5 máquina de estados de compactación de tres modos; §7.2.6 carácter de control mod-211
Enlace GS1 Composite y CC-C	ISO/IEC 24723:2010	§5.4 semántica de la palabra de código CCSI; §5.1 admisibilidad del portador
Palabras de código GS1 Composite CC-A	ISO/IEC 24723:2010	§5 encodación de cadena binaria de propósito general con conversión base-928
Estructura de símbolo rMQR	ISO/IEC 23941:2022	§6.3.2 Tabla 1 dimensiones de versión; §7.8.2 máscara fija; Anexo C / Anexo I referencia de información de formato
Micro QR	ISO/IEC 18004	Capacidad e información de formato de Micro QR M1–M4
Han Xin Code	ISO/IEC 20830:2021	Estructura de símbolo; patrones de localización y alineación; modos GB 2312 Región 1/2; ECC Reed–Solomon; enmascaramiento
JabCode	ISO/IEC 23634	Estructura de símbolo, color y ECC
Simbología postal	USPS-B-3200	Estructura de campo de Intelligent Mail Barcode

Estado de soporte por simbología

Una variante está Verificada cuando un fixture bajo pro/tests/** la ejercita, preferiblemente una traza de referencia fijada a un ejemplo resuelto publicado. Una variante distribuida sin fixture dedicado permanece Declarada. Una variante sin codificador es No compatible.

Simbología / variante	Estado	Evidencia (ruta de prueba)	Notas
Micro QR (M1–M4)	Verificada	pro/tests/Unit/Barcode/MicroQrEncoderTest.php	A nivel unitario; un fixture de traza de referencia con ejemplo resuelto es una tarea de relleno registrada
DotCode	Verificada	pro/tests/Unit/Barcode/DotCodeEncoderTest.php; DotCodeGfArithmeticTest.php	Aritmética de campo de Galois cubierta; sin ida y vuelta con decodificador de terceros
Han Xin Code	Verificada	pro/tests/Unit/Barcode/HanXinEncoderTest.php; HanXinRsEncodingTest.php	Ruta de codificación Reed–Solomon ejercitada explícitamente
JabCode (1–61 símbolos, 4–256 colores, ECC 0–10)	Verificada	pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php (+ 11 suites de componentes en el mismo directorio)	Cascada multisímbolo y rango de ECC ejercitados; sin ida y vuelta con decodificador de terceros
USPS Intelligent Mail Barcode	Verificada	pro/tests/Unit/Barcode/ImbEncoderTest.php; ImbRoutingCodeTest.php	Validación de código de enrutamiento y longitud de 20/25/29/31 dígitos ejercitada
rMQR — las 32 versiones ISO/IEC 23941	Verificada	pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php; RmqrAnnexCFormatInfoTest.php; pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php	Pares de versión y EC comprobados contra la Tabla 1 de ISO/IEC 23941; valores de referencia de información de formato del Anexo C / Anexo I
GS1 DataBar — Omnidirectional / Truncated	Verificada	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php	Byte a byte igual al ejemplo resuelto del Anexo F.1; Truncated comparte la codificación con altura reducida
GS1 DataBar — Stacked / Stacked Omnidirectional	Verificada	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php	División de filas derivada de la traza del Anexo F.1; construcción de separadores según §5.4 y §5.5
GS1 DataBar — Limited	Verificada	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php; pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php	Byte a byte igual al ejemplo resuelto del Anexo F.2 (artículo 00098765432105)
GS1 DataBar — Expanded	Verificada	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php; pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php	Byte a byte igual al ejemplo resuelto del Anexo F.3 ((10)12A); ida y vuelta con decodificador independiente contra zxing-cpp y ZBar
GS1 DataBar — Expanded Stacked	Verificada	pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php (casos apilados); la ida y vuelta de integración anterior	Misma canalización de datos que Expanded de una fila; partición de filas y separadores del §7.2.8 verificados
GS1 Composite — CC-C (portador PDF417)	Verificada	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php; CompositeRoundtripTest.php; CompositeLinkageTest.php	Interacción de la palabra de código CCSI 920 y el indicador de enlace cubierta
GS1 Composite — CC-A	Parcial	pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php; pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php	Generación de palabras de código Verificada (base-928, autocomprobación de ida y vuelta); renderizado de símbolo completo no compatible: encode() falla a prueba de fallos
GS1 Composite — CC-B	No compatible	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php (verifica el rechazo a prueba de fallos)	Sin codificación 2D; el auxiliar de enlace (CCSI 901) sigue disponible
Analizador de IA GS1	Verificada	pro/tests/Unit/Barcode/Gs1DataParserTest.php; Gs1DataParserFnc1Test.php	Ambos formatos de entrada y las tres salidas de secuencia de bytes de portador ejercitados
Validador de cadena de suministro GS1	Verificada	pro/tests/Unit/Barcode/Gs1ValidatorTest.php; Gs1ValidatorCrossAiTest.php; pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php	Dígitos de control, combinaciones obligatorias entre IA y lógica de fechas ejercitados

Notas de desarrollo

• Los anclajes de evidencia de esta página son rutas de prueba bajo pro/tests/**; el repositorio no distribuye ningún directorio examples/ para este módulo.
• Los siete nombres de capacidad enumerados en Disponibilidad y licencias son las claves que vincula el proveedor de servicio. El codificador IMB se construye directamente y no porta ninguna clave de registro.
• CC-A emite únicamente el método de encodación de propósito general; los métodos comprimidos específicos de aplicación son un residuo de densidad documentado, no una carencia de corrección.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública admitida. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.

Véase también

• Descripción general de la capacidad de códigos de barras (NextPDF Pro)
• Referencia detallada de gráficos
• Módulo de códigos de barras de Core