Generar códigos de barras 1D y 2D en un PDF

De un vistazo

Esta receta dibuja códigos de barras 1D y 2D directamente en una página PDF. El trait HasBarcodes del núcleo proporciona write1DBarcode() y write2DBarcode(). Ambos dibujan el símbolo como operadores de trazado PDF nativos en la página actual, de modo que la salida es contenido vectorial simple y determinista. La receta sigue examples/10-barcodes.php.

Instalación

composer require nextpdf/core:^3

No se necesita ninguna extensión adicional. Los codificadores de códigos de barras están escritos en PHP puro, y los símbolos se dibujan con el operador estándar de rectángulo de PDF (ISO 32000-2 §8.5).

Panorama conceptual

Un código de barras se dibuja; no se incrusta como imagen. La carga útil corresponde a los datos que se codifican, como un número de producto o una dirección web.

write1DBarcode() codifica la carga útil en un patrón de bar/space para el BarcodeType elegido y luego emite una secuencia de rectángulos rellenos. write2DBarcode() construye una matriz de módulos para el Barcode2DType elegido y emite un rectángulo relleno por cada módulo oscuro. Data Matrix y QR Code usan corrección de errores Reed-Solomon, de modo que un escáner puede recuperar los datos aunque una parte del símbolo esté dañada.

Cada módulo es un trazado re … f determinista sin fuente de entropía, por lo que el contenido del código de barras en sí es totalmente reproducible. El perfil de reproducibilidad es structural porque el documento que lo rodea aún incluye átomos propios de cada guardado: el /ID del tráiler y las marcas de tiempo /CreationDate y /ModDate. El harness compara la estructura normalizada con qpdf tras eliminar esos átomos.

Superficie de la API

NextPDF\Core\Concerns\HasBarcodes (incorporado en Document):

write1DBarcode(string $code, BarcodeType $type, ?float $x = null, ?float $y = null, float $w = 0, float $h = 30, float $barWidth = 0.4, bool $skipZeroWidthBars = true): static
write2DBarcode(string $code, Barcode2DType $type, ?float $x = null, ?float $y = null, float $w = 0, float $h = 0, float $moduleSize = 1.0, string $ecLevel = 'L', ?int $mask = null, ?int $version = null, bool $gs1 = false, bool $dmre = false, bool $rectangular = false): static

Una simbología es un estándar de código de barras que define cómo los datos se convierten en barras o módulos. BarcodeType enumera las simbologías 1D (C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …), y Barcode2DType enumera las simbologías 2D (QRCode, DataMatrix, PDF417, HanXin, MicroQR, …).

Ejemplo de código — Inicio rápido

<?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->setTitle('Barcode Quick Start');
$doc->addPage();

$doc->write1DBarcode('NEXTPDF-2026', BarcodeType::C128, x: 15, y: 30, w: 80, h: 20);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: 60, w: 40, h: 40);

$doc->save(__DIR__ . '/barcodes.pdf');
echo "Wrote barcodes.pdf\n";

Ejemplo de código — Producción

El ejemplo completo que aparece a continuación, ejecutable por el harness, refleja examples/10-barcodes.php. Escribe el PDF en la ruta que el harness proporciona a través de NEXTPDF_COOKBOOK_OUTPUT y usa un archivo local cuando se ejecuta manualmente. Luego, el harness de reproducibilidad puede ejecutarlo dos veces y comprobar la identidad estructural. La estructura se normaliza con qpdf, con el /ID propio de cada guardado y los átomos de marca de tiempo eliminados.

<?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->setTitle('Barcode Examples');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Barcode Examples', newLine: true);
$doc->ln(5);

// --- 1D barcodes ---
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, '1D Barcodes', newLine: true);
$doc->ln(3);

$doc->setFont('helvetica', '', 10);
$doc->cell(0, 6, 'Code 128:', newLine: true);
$doc->write1DBarcode('NEXTPDF-2026', BarcodeType::C128, x: 15, y: null, w: 80, h: 20);
$doc->ln(28);

$doc->cell(0, 6, 'EAN-13:', newLine: true);
$doc->write1DBarcode('4006381333931', BarcodeType::EAN13, x: 15, y: null, w: 60, h: 20);
$doc->ln(28);

// --- 2D barcodes ---
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, '2D Barcodes', newLine: true);
$doc->ln(3);

$doc->setFont('helvetica', '', 10);
$doc->cell(0, 6, 'QR Code (URL):', newLine: true);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: null, w: 40, h: 40);
$doc->ln(48);

$doc->cell(0, 6, 'DataMatrix:', newLine: true);
$doc->write2DBarcode('NextPDF-DM-2026', Barcode2DType::DataMatrix, x: 15, y: null, w: 30, h: 30);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/barcodes.pdf');

echo "Wrote barcodes PDF (Code 128, EAN-13, QR Code, DataMatrix)\n";

Salida esperada:

Wrote barcodes PDF (Code 128, EAN-13, QR Code, DataMatrix)

Casos límite y trampas

La validez de la carga útil depende de la simbología. EAN13 espera 12 o 13 dígitos. Si la carga útil no es válida, se lanza una excepción antes de que se escriba cualquier contenido. UPCA, ISBN e ISSN tienen sus propias reglas de longitud y de dígito de control.
x/y son opcionales. Cuando se omiten, el código de barras se coloca en la posición actual del cursor. Pasar coordenadas explícitas permite obtener una disposición predecible.
w = 0 ajusta el tamaño automáticamente. Un ancho cero permite que el codificador elija un ancho de módulo natural. Pasar un ancho positivo permite ajustarlo a una caja de tamaño fijo.
Nivel de corrección de errores 2D. write2DBarcode() usa de forma predeterminada ecLevel: 'L', el nivel más bajo. Conviene aumentarlo ('M', 'Q', 'H') para QR Codes que deban resistir el deterioro de impresión. Los niveles más altos agrandan la matriz.
Identificadores de aplicación GS1. Pasar gs1: true a write2DBarcode(), o usar BarcodeType::GS1_128, para datos estructurados GS1 con el prefijo FNC1.
Una página se crea de forma implícita. Cuando se llama a un método de código de barras antes de addPage(), NextPDF añade primero una página. Esto resulta práctico, pero conviene llamar a addPage() de forma explícita cuando la geometría de la página importa.

Rendimiento

La codificación es O(longitud de la carga útil) para 1D y O(área de la matriz) para 2D, y ambas se ejecutan en escala de microsegundos. Cada módulo se emite como un operador de trazado re … f, de modo que un QR Code denso añade unos pocos kilobytes de flujo de contenido. No hay etapa de rasterización, así que la memoria se mantiene plana independientemente del tamaño del símbolo. La receta se mantiene holgadamente dentro del presupuesto de 1500 ms / 64 MB.

Notas de seguridad

Un código de barras contiene la carga útil que se le pase, así que conviene tratar su valor igual que cualquier otra entrada no confiable en el extremo que lo consume. La biblioteca no firma ni autentica la carga útil. Un símbolo 2D no cifra los datos: cualquiera con un escáner puede leerlo.

Conformidad

Declaración	Especificación	Cláusula
Los módulos del código de barras se dibujan con el operador de construcción de trazado de rectángulo.	ISO 32000-2	§8.5
Los caracteres de símbolo Code 128 usan la estructura definida de elementos bar/space.	ISO/IEC 15417	§4.3.1
Los símbolos Data Matrix emplean corrección de errores Reed-Solomon.	ISO/IEC 16022	§7.6.1
Los datos del QR Code se dividen en bloques de corrección de errores.	ISO/IEC 18004	§7.5.2

NextPDF implementa las codificaciones de las simbologías citadas, pero no declara una certificación formal respecto de los estándares de códigos de barras. Los documentos del corpus de simbologías de códigos de barras tienen un tope de licencia en el nivel C. Las citas son únicamente punteros de clause-id y reference_id, y no se reproduce ningún texto del estándar.