Código de barras: codificadores de simbologías 1D y 2D

De un vistazo

El módulo Barcode es la capa de implementación de las simbologías. Codifica simbologías lineales (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, códigos postales) y simbologías matriciales (QR Code, Data Matrix, PDF417). Calcula la corrección de errores correspondiente. Registra cada codificador mediante los contratos de código de barras para que el escritor de documentos pueda pintar el resultado. Las definiciones de esos contratos residen en una página aparte; la nota siguiente lo detalla.

Una única página canónica por asunto. Las interfaces que debe satisfacer un codificador (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) están documentadas en Contratos / Código de barras. Esta página documenta los codificadores concretos que implementan esos contratos. Ambas páginas son complementarias, no duplicadas. Para la SPI, consulte la página de contratos; para las simbologías, esta página.

Instalación

composer require nextpdf/core:^3

Visión general conceptual

Un codificador de código de barras convierte una cadena de carga útil en una matriz de módulos (2D) o en una secuencia de barras (1D) que el escritor pinta como gráficos PDF. Este módulo incluye los codificadores concretos.

Barcode1D es el motor lineal. BarcodeType enumera las simbologías lineales admitidas: Code 39 (con y sin suma de comprobación), Code 93, la familia Code 128, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved y Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB) y MSI. generate() devuelve un objeto de valor BarcodeData que describe el patrón de barras.

Los codificadores 2D — QrEncoder, DataMatrixEncoder, Pdf417Encoder — implementan BarcodeEncoderInterface y devuelven una matriz Barcode2DData. Barcode2DType enumera las simbologías matriciales que reconoce el motor, incluidas QR Code, Data Matrix y PDF417. Simbologías adicionales como Micro QR, rMQR, GS1 DataBar y Han Xin figuran para el enrutamiento del registro. El conjunto de codificadores que respalda cada una depende de la edición. La corrección de errores matricial se calcula en un campo de Galois. GaloisField y GaloisFieldPrime proporcionan la aritmética Reed-Solomon compartida por los codificadores QR, Data Matrix y PDF417.

BarcodeEncoderRegistry es el mecanismo de búsqueda. Implementa la ContainerInterface de PSR-11, ofrece un registro predeterminado mediante createDefault() y resuelve una simbología a su codificador con resolve(). El código de la aplicación rara vez accede directamente a un codificador. La fachada de alto nivel Document::write1DBarcode() / write2DBarcode() nombra una simbología y el registro suministra el codificador. El motor 1D es @since 1.0.0. Los codificadores 2D son @since 1.3.0. El registro es @since 3.0.0.

Superficie de la API

Clase	Miembros clave	Función
Barcode1D	generate(string $code, BarcodeType $type): BarcodeData	Codificador de simbologías lineales (@since 1.0.0)
QrEncoder	encode(string $data, array $options = []): Barcode2DData	Codificador de QR Code (@since 1.3.0)
DataMatrixEncoder	encode(string $data, array $options = []): Barcode2DData	Codificador de Data Matrix (@since 1.3.0)
Pdf417Encoder	encode(string $data, array $options = []): Barcode2DData	Codificador de PDF417 (@since 1.3.0)
BarcodeEncoderRegistry	createDefault(), register(), resolve(), has(), get(), registered()	Registro de codificadores PSR-11 (@since 3.0.0)
BarcodeType / Barcode2DType	casos de enum	Enumeraciones de simbologías admitidas
GaloisField / GaloisFieldPrime	aritmética de campos finitos	Corrección de errores Reed-Solomon

Para consultar la tabla PHPDoc completa, ejecute composer docs:generate-api-php -- --module=Barcode.

Ejemplo de código — Inicio rápido

Fuente: examples/10-barcodes.php. La fachada resuelve, a través del registro, el codificador correspondiente a la simbología.

<?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->addPage();

$doc->write1DBarcode('4006381333931', BarcodeType::EAN13, x: 15, y: null, w: 60, h: 20);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: 40, w: 40, h: 40);

$doc->save(__DIR__ . '/output/10-barcodes.pdf');

Ejemplo de código — Producción

Resolver un codificador 2D directamente a través del registro y limitar la carga útil antes de codificar.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Barcode\Barcode2DType;
use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class TrackingCodeService
{
    private const int MAX_PAYLOAD = 512;

    public function __construct(
        private BarcodeEncoderRegistry $registry,
        private LoggerInterface $logger,
    ) {}

    /** @return \NextPDF\Barcode\Barcode2DData */
    public function encode(string $trackingId): \NextPDF\Barcode\Barcode2DData
    {
        if (strlen($trackingId) > self::MAX_PAYLOAD) {
            throw new \LengthException('Tracking payload exceeds the encode bound.');
        }

        try {
            $encoder = $this->registry->resolve(Barcode2DType::QRCode->value);

            return $encoder->encode($trackingId, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('Barcode encode failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

Casos límite y aspectos a tener en cuenta

• Una carga útil lineal que infringe el conjunto de caracteres de una simbología o la regla del dígito de control lanza BarcodeException. EAN/UPC calculan y añaden el dígito de control. No añadirlo previamente.
• El array $options 2D es específico de cada simbología (por ejemplo, un nivel de corrección de errores para QR). La mayoría de los codificadores ignoran las claves desconocidas. Conviene verificar cada clave en la propia documentación del codificador.
• Barcode2DType enumera más simbologías que las que la edición del núcleo cubre con codificadores. BarcodeEncoderRegistry::resolve() lanza una excepción ante una simbología no registrada en lugar de devolver un marcador de posición.
• Los codificadores registrados son instancias compartidas. Mantenerlos sin estado más allá de la configuración del constructor. El estado específico de una llamada corrompe las representaciones concurrentes.
• Una carga útil demasiado larga produce una matriz más densa y más grande. Limitar la longitud de la carga útil antes de codificar para evitar una denegación de servicio por el tamaño del símbolo.

Rendimiento

El coste de codificación escala con la longitud de la carga útil y el tamaño de la matriz, no con la búsqueda en el registro, que es O(1). Una carga útil corta de Code 128 se codifica en microsegundos. Un QR Code denso con corrección de errores alta es el caso más pesado. Se mantiene dentro del presupuesto de 1500 ms de tiempo de pared / 64 MB de pico para la página de ejemplo multisímbolo. El perfil de reproducibilidad es bitwise. La misma carga útil y las mismas opciones siempre producen la misma matriz de módulos y los mismos bytes pintados.

Notas de seguridad

Las cargas útiles de los códigos de barras suelen poder estar controladas por atacantes: una URL escaneada, un número de serie, un código de seguimiento. Los codificadores codifican bytes. No los interpretan. Un QR Code que codifica una URL hostil es un QR Code válido, por lo que la confianza en la carga útil es responsabilidad del consumidor. Limitar la longitud de la carga útil antes de codificar permite mantener el tamaño de la matriz — y, por tanto, el trabajo y el tamaño de salida — dentro de un presupuesto. Tratar cualquier dato decodificado de un código de barras en otro lugar como entrada no confiable cuando vuelva a entrar en la aplicación. Consulte el modelo de amenazas del motor en /modules/core/security/.

Conformidad

Afirmación	Estándar	Referencia
Los símbolos QR Code siguen la especificación de simbología matricial QR Code.	ISO/IEC 18004	Simbología QR Code
Los símbolos Data Matrix siguen la especificación de simbología Data Matrix.	ISO/IEC 16022	Simbología Data Matrix
Los símbolos PDF417 siguen la especificación de simbología PDF417.	ISO/IEC 15438	Simbología PDF417
Los símbolos Code 128 siguen la especificación de simbología lineal Code 128.	ISO/IEC 15417	Simbología Code 128
Los símbolos EAN/UPC siguen la especificación de simbología EAN/UPC.	ISO/IEC 15420	Simbología EAN/UPC

Estos estándares de simbología no están presentes en el corpus de citas verificables, por lo que no se registra ningún reference_id. El motor parafrasea el requisito y cita la fuente por número y cláusula. Consulte los estándares publicados para conocer las reglas de codificación autorizadas. Los codificadores se ejercitan mediante tests/Unit/Barcode/. La corrección frente a las especificaciones de simbología es responsabilidad del conjunto de pruebas, no una declaración de conformidad PDF de extremo a extremo.

Véase también

• Contratos / Código de barras — interfaces de codificador que implementan estas clases (la SPI).
• Módulo Graphics — capa de dibujo que pinta la matriz codificada.
• Módulo Document — fachada de alto nivel write1DBarcode() / write2DBarcode().
• Visión general de conformidad
• Modelo de seguridad del motor