Gere códigos de barras 1D e 2D em um PDF

Visão geral

Esta receita desenha códigos de barras unidimensionais (1D) e bidimensionais (2D) diretamente em uma página no formato Portable Document Format (PDF). O trait HasBarcodes do Core fornece write1DBarcode() e write2DBarcode(). Ambos os métodos desenham o símbolo como operadores nativos de path do PDF na página atual, de modo que a saída seja conteúdo vetorial simples e determinístico. A receita usa examples/10-barcodes.php como base.

Instalação

composer require nextpdf/core:^3

Você não precisa de nenhuma extensão adicional. Os codificadores de códigos de barras são PHP puro, e o NextPDF desenha os símbolos com o operador de retângulo PDF padrão (ISO 32000-2 §8.5).

Visão conceitual

Um código de barras é desenhado, não incorporado como imagem. O payload corresponde aos dados que você codifica, como um número de produto ou um endereço web.

write1DBarcode() codifica o payload em um padrão de bar/space para o BarcodeType escolhido e, em seguida, emite uma sequência de retângulos preenchidos. write2DBarcode() constrói uma matriz de módulos para o Barcode2DType escolhido e emite um retângulo preenchido para cada módulo escuro. Data Matrix e QR Code usam correção de erros Reed-Solomon, o que permite que um leitor recupere os dados mesmo quando parte do símbolo está danificada.

Cada módulo é um path re … f determinístico, sem fonte de entropia, de modo que o conteúdo do código de barras em si seja totalmente reproduzível. O perfil de reprodutibilidade é structural porque o documento ao redor ainda carrega átomos definidos a cada gravação: o /ID do trailer, além dos timestamps /CreationDate e /ModDate. O harness compara a estrutura normalizada pelo qpdf depois que esses átomos são removidos.

Superfície da API

NextPDF\Core\Concerns\HasBarcodes (incluído em 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

Uma simbologia é um padrão de código de barras que define como os dados são convertidos em barras ou módulos. BarcodeType lista as simbologias 1D (C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …), e Barcode2DType lista as simbologias 2D (QRCode, DataMatrix, PDF417, HanXin, MicroQR, …).

Exemplo de código — Início 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";

Exemplo de código — Produção

O exemplo completo abaixo, executável pelo harness, espelha examples/10-barcodes.php. Ele grava o PDF no caminho que o harness fornece por meio de NEXTPDF_COOKBOOK_OUTPUT e usa um arquivo local como fallback quando você o executa manualmente. Em seguida, o harness de reprodutibilidade pode executá-lo duas vezes e verificar a identidade estrutural. A estrutura é normalizada pelo qpdf, removendo os átomos de /ID e timestamp definidos a cada gravação.

<?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";

Saída esperada:

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

Casos extremos e pegadinhas

A validade do payload é específica de cada simbologia. EAN13 espera 12 ou 13 dígitos. Um payload inválido lança uma exceção antes que o NextPDF grave qualquer conteúdo. UPCA, ISBN e ISSN têm suas próprias regras de comprimento e dígito verificador.
x/y são opcionais. Quando você os omite, o código de barras é posicionado na posição atual do cursor. Passe coordenadas explícitas para um layout previsível.
w = 0 dimensiona automaticamente. Uma largura zero permite que o codificador escolha uma largura de módulo natural. Passe uma largura positiva para caber em uma caixa de tamanho fixo.
Nível de correção de erros 2D. write2DBarcode() usa, por padrão, ecLevel: 'L', o nível mais baixo. Aumente-o ('M', 'Q', 'H') para QR Codes que precisam resistir a danos de impressão. Níveis mais altos aumentam a matriz.
Identificadores de aplicação GS1. Passe gs1: true para write2DBarcode(), ou use BarcodeType::GS1_128, para dados estruturados em GS1 com o prefixo FNC1.
Uma página é criada implicitamente. Quando você chama um método de código de barras antes de addPage(), o NextPDF adiciona uma página primeiro. Isso é conveniente, mas chame addPage() explicitamente quando a geometria da página for importante.

Desempenho

A codificação é O(payload length) para 1D e O(matrix area) para 2D, e ambas executam em escala de microssegundos. Cada módulo é um operador de path re … f, de modo que um QR Code denso adiciona alguns kilobytes de content stream. Não há etapa de rasterização, então a memória permanece constante independentemente do tamanho do símbolo. A receita fica bem dentro do orçamento de 1500 ms / 64 MB.

Notas de segurança

Um código de barras carrega qualquer payload que você passar, então trate o valor do código de barras como qualquer outra entrada não confiável do lado consumidor. A biblioteca não assina nem autentica o payload. Um símbolo 2D não é criptografia: qualquer pessoa com um leitor pode lê-lo.

Conformidade

Afirmação	Especificação	Cláusula
Os módulos do código de barras são desenhados com o operador de construção de path de retângulo.	ISO 32000-2	§8.5
Os caracteres de símbolo do Code 128 usam a estrutura de elemento bar/space definida.	ISO/IEC 15417	§4.3.1
Os símbolos Data Matrix empregam correção de erros Reed-Solomon.	ISO/IEC 16022	§7.6.1
Os dados do QR Code são divididos em blocos de correção de erros.	ISO/IEC 18004	§7.5.2

O NextPDF implementa as codificações de simbologia citadas, mas não declara certificação formal em relação aos padrões de código de barras. Os documentos do corpus de simbologia de código de barras têm limite de licença no Tier C. As citações usam apenas ponteiros de clause-id e reference_id, e nenhum texto do padrão é reproduzido.