Pro edición

Barcode

De un vistazo

NextPDF Pro añade simbologías de código de barras especializadas 2D y de cadena de suministro sobre las simbologías lineales y QR de la edición de código abierto. Cada simbología se renderiza directamente en una superficie de página de PDF como un flujo de contenido determinista.

Disponibilidad y licencia

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa titularidad no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Instalación

composer require nextpdf/pro:^3

Los codificadores de Pro se registran a sí mismos a través del registro estándar de codificadores de código de barras. Las aplicaciones que construyen su propio registro pueden volver a registrar los codificadores de Pro de forma explícita a través del proveedor de servicios publicado.

Descripción conceptual

La edición de código abierto cubre las simbologías lineales y QR de uso cotidiano. NextPDF Pro amplía el mismo registro con simbologías especializadas para uso minorista, logístico, postal e industrial de alta densidad:

Micro QR Code — la variante QR compacta para el espacio reducido de etiquetas pequeñas.
DotCode — una simbología de matriz de puntos diseñada para el marcado industrial de alta velocidad.
Han Xin Code — una simbología 2D con capacidad nativa de texto CJK de conjunto grande, según ISO/IEC 20830.
JabCode — una simbología 2D policroma con encadenamiento de múltiples símbolos.
rMQR — la variante Micro QR rectangular para etiquetas estrechas y anchas.
GS1 DataBar — la familia de simbologías GS1 minorista y de cupones.
GS1 Composite (CC-C) — una base 1D enlazada más un componente de extensión 2D PDF417 de alta densidad que transporta datos de identificadores de aplicación GS1. (La codificación de componentes extendidos 2D CC-A y CC-B no es compatible en esta versión; consulte la matriz de compatibilidad).

Cada codificador produce un objeto de datos de código de barras que el renderizador de páginas convierte en operadores de contenido de PDF. La codificación es determinista: la misma entrada y opciones siempre producen el mismo patrón de módulos, lo que mantiene reproducibles los documentos firmados y archivados.

La referencia detallada de código de barras lleva una matriz de compatibilidad por simbología con evidencia. Para cada simbología y variante, la matriz registra uno de tres estados: una fijación (fixture) de conformidad en el repositorio la ejercita (Verified), la superficie de implementación la afirma sin una fijación dedicada (Claimed), o queda fuera de alcance (Not supported). NextPDF informa de la matriz con honestidad: una variante que incluye un codificador pero carece de una fijación de traza de referencia permanece Claimed con una nota de relleno (backfill) en lugar de sobreestimarse.

Por qué funciona así

Cada codificador de Pro es una función pura: la misma carga útil y opciones siempre producen la misma matriz de módulos, sin estado oculto ni aleatoriedad sembrada. Ese determinismo es la decisión que sostiene todo. Permite que un código de barras haga un recorrido de ida y vuelta a través de un documento firmado o archivado sin perturbar el flujo de bytes, de modo que un nuevo renderizado nunca invalida una firma. También hace que la conformidad sea auditable: la matriz de compatibilidad fija cada simbología a una traza de referencia almacenada, comprobada bit a bit contra un archivo de referencia (golden file). Ampliar el BarcodeEncoderRegistry de Core en lugar de bifurcarlo mantiene estas garantías idénticas en las ediciones abierta y Pro.

Antecedentes de diseño: Los mismos bytes cada vez: PDF reproducibles.

Superficie de la API

composer require nextpdf/pro:^3

La superficie pública de código de barras de Pro consta de:

Un punto de entrada estático de proveedor de servicios que registra los codificadores 2D de Pro en un registro de codificadores de código de barras (MicroQR, DotCode, HanXin, JabCode, RMQR, GS1DataBar y la clave del componente GS1 Composite CC-C gs1-composite-cc-c). La codificación de componentes extendidos 2D CC-A y CC-B de GS1 Composite no es compatible en esta versión y no se registra.
Un analizador de identificadores de aplicación GS1 que acepta tanto cadenas AI legibles por humanos como URI de GS1 Digital Link y produce secuencias de bytes codificadas para portadores GS1-128, QR Code y Data Matrix.
Un validador de cadena de suministro GS1 que comprueba los dígitos de control, la estructura de AI, la lógica de fechas y las combinaciones obligatorias de AI del perfil del sector.

La tabla completa generada de firmas de método se renderiza en la referencia detallada de código de barras.

Ejemplo de código — Inicio rápido

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

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

Ejemplo de código — Producción

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 límite y trampas

El registro predeterminado preenlaza las entradas de codificadores de Pro de forma diferida (lazy) y las regula a través del registro de capacidades. Una llamada explícita a BarcodeProServiceProvider::register() es la alternativa compatible cuando una aplicación compone su propio registro sin valores predeterminados.
El nuevo registro es idempotente: una segunda llamada a register() reemplaza el primer enlace en lugar de generar un error.
La cobertura de variantes de GS1 DataBar es parcial por diseño. Omnidirectional, Truncated, Stacked, Stacked Omnidirectional y Limited están verificadas por referencia; Expanded y Expanded Stacked quedan fuera de alcance en esta versión. Consulte la matriz de compatibilidad.
rMQR acepta todas las versiones de ISO 23941 a través del conjunto de conformidad validado por el anexo. Los metadatos de seguimiento de alcance anteriores a la posterior ampliación del rango de tamaños pueden subestimar esto; la matriz de compatibilidad registra la realidad verificada en código.

Rendimiento

El costo de codificación escala con la longitud de la carga útil y el tamaño del símbolo de destino. Cada simbología compone su símbolo en una sola pasada sin reflujo. Los encadenamientos de múltiples símbolos de JabCode escalan con el recuento de símbolos (1–61). La codificación mantiene la matriz de módulos en memoria; la versión de símbolo seleccionada más grande acota el costo.

Notas de seguridad

Los codificadores de código de barras no ejecutan el contenido de la carga útil; lo codifican como datos. La validación GS1 rechaza las estructuras AI mal formadas y los dígitos de control no válidos antes de la codificación, lo que evita que una cadena de cadena de suministro mal formada produzca un símbolo escaneable pero no conforme. Los codificadores no registran por sí mismos ninguna carga útil; las aplicaciones deben depurar las cargas útiles sensibles de sus propios registros.

Conformidad

Cada simbología sigue su estándar 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 la simbología postal). El mapeo de conformidad a nivel de cláusula con identificadores de cita se renderiza en la referencia detallada de código de barras.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de API compatible. 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 de alcance.