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. As citações acima apontam para a cláusula correspondente de cada padrão; nenhum texto do padrão é reproduzido aqui.