Контракты / Barcode

Кратко

Домен штрихкодов определяет четыре контракта: одномерный (1D) кодировщик, двумерный (2D) кодировщик, универсальный кодировщик, обнаруживаемый через реестр, и парсер данных GS1. Вместе они задают форму, которой должны соответствовать сервисы штрихкодов. Реализации символик регистрируются под этими контрактами.

Установка

composer require nextpdf/core:^3

Концептуальный обзор

Кодировщик штрихкода преобразует строку полезной нагрузки в матрицу модулей, которую отрисовывает writer Portable Document Format (PDF). NextPDF разделяет контракты кодировщиков по размерности. Barcode1DEncoderInterface обрабатывает линейные символики, включая Code 128 и EAN-13, и возвращает объект-значение BarcodeData. Barcode2DEncoderInterface обрабатывает матричные символики, включая Quick Response (QR) Code и Data Matrix. Он возвращает объект-значение Barcode2DData с картой параметров для настроек, специфичных для символики, например уровня коррекции ошибок.

BarcodeEncoderInterface — универсальный контракт поставщика сервиса. Его реализует любой 2D-кодировщик, обнаруживаемый через BarcodeEncoderRegistry. Контракт возвращает либо монохромную матрицу Barcode2DData, либо цветную матрицу BarcodeColorData, поэтому зарегистрированный кодировщик может выдавать цветной символ без отдельного интерфейса. Предполагается, что кодировщики не хранят состояние, кроме конфигурации, заданной при создании. Реестр возвращает один общий экземпляр для каждого зарегистрированного типа, поэтому любое состояние на уровне вызова было бы дефектом.

Gs1DataParserInterface — контракт структурированных данных. Он разбирает строку элементов GS1 в типизированный объект, а затем повторно кодирует этот объект для носителя QR Code, Data Matrix или Code 128. Так грамматика GS1 остаётся отделена от символики. Парсер проверяет идентификаторы применения (Application Identifiers) один раз. Методы, специфичные для носителя, форматируют одну и ту же разобранную структуру для каждой цели. Все четыре контракта имеют статус stable. BarcodeEncoderInterface стабилен начиная с 3.0.0; остальные — начиная с 1.0.0. Новые методы появляются только с реализациями по умолчанию.

Поверхность API

Тип	Вид	Ключевые члены	Стабильность	Начиная с
`Barcode1DEncoderInterface`	interface	`encode(string): BarcodeData`	stable (стабильный)	1.0.0
`Barcode2DEncoderInterface`	interface	`encode(string, array): Barcode2DData`	stable (стабильный)	1.0.0
`BarcodeEncoderInterface`	interface	`encode(string, array): Barcode2DData\|BarcodeColorData`	stable (стабильный)	3.0.0
`Gs1DataParserInterface`	interface	`parse()`, `encodeForQrCode()`, `encodeForDataMatrix()`, `encodeForCode128()`	stable (стабильный)	1.0.0

В 2D-контрактах массив $options зависит от символики, например от уровня коррекции ошибок для QR Code. Контракт не ограничивает его ключи. Каждый зарегистрированный кодировщик документирует собственный набор параметров.

Пример кода — быстрый старт

<?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', '', 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, 'QR Code (URL):', newLine: true);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: null, w: 40, h: 40);

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

write1DBarcode() и write2DBarcode() находят кодировщик через реестр. Код вашего приложения редко обращается к контрактам напрямую. Вы указываете символику, а реестр предоставляет кодировщик.

Пример кода — продакшен

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Barcode2DEncoderInterface;
use NextPDF\Contracts\Gs1DataParserInterface;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class Gs1LabelService
{
    public function __construct(
        private Gs1DataParserInterface $parser,
        private Barcode2DEncoderInterface $dataMatrix,
        private LoggerInterface $logger,
    ) {}

    /**
     * Parse a GS1 element string and encode it as a Data Matrix.
     *
     * @param string $elementString A GS1 element string with Application Identifiers.
     */
    public function encodeLabel(string $elementString): \NextPDF\Barcode\Barcode2DData
    {
        try {
            $parsed = $this->parser->parse($elementString);
            $payload = $this->parser->encodeForDataMatrix($parsed);

            return $this->dataMatrix->encode($payload, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('GS1 label encoding failed', [
                'error' => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

Сервис зависит от контрактов парсера и кодировщика. Блок catch логирует и повторно выбрасывает конкретное исключение BarcodeException; он никогда не перехватывает базовое \Exception.

Краевые случаи и подводные камни

Зарегистрированный кодировщик используется совместно. Состояние на уровне вызова в кодировщике нарушает параллельную отрисовку. Держите кодировщики без состояния, кроме конфигурации конструктора.
BarcodeEncoderInterface::encode() может возвращать цветные или монохромные данные. Код, который их потребляет, должен обрабатывать как Barcode2DData, так и BarcodeColorData, а не предполагать монохром.
2D-массив $options не проверяется контрактом. Большинство кодировщиков молча игнорируют неизвестные ключи. Сверяйте имя ключа с собственной документацией кодировщика.
Разбор GS1 строго следует грамматике. Строка элементов с неизвестным идентификатором применения (Application Identifier) вызывает BarcodeException, а не возвращает частично разобранные данные. Проверяйте входные данные на стороне источника.
Контракты 1D и 2D невзаимозаменяемы. Передача полезной нагрузки QR в 1D-кодировщик даёт недопустимый символ. Реестр маршрутизирует по типу символики, поэтому предпочитайте реестр прямому вызову контракта.

Производительность

Стоимость кодирования растёт с длиной полезной нагрузки и размером целевой матрицы, а не с тем, какой контракт вы вызываете. Короткая полезная нагрузка Code 128 кодируется за микросекунды. Плотный QR Code с высокой коррекцией ошибок — самый тяжёлый 2D-случай. Он всё равно укладывается в performance_budget: 1500 мс по времени и 64 МБ по пиковому потреблению памяти для страницы примера с несколькими символами. Матрица вычисляется один раз и отрисовывается операторами PDF. Воспроизводимость имеет профиль bitwise, потому что одна и та же полезная нагрузка с одними и теми же параметрами всегда даёт одну и ту же матрицу модулей. Поиск в реестре выполняется за O(1). Основную работу выполняет алгоритм символики.

Замечания по безопасности

Полезные нагрузки штрихкодов часто могут контролироваться злоумышленником: например, отсканированный Uniform Resource Locator (URL), серийный номер или код отслеживания. Контракты кодируют байты. Они их не интерпретируют. QR Code, кодирующий враждебный URL, по-прежнему является допустимым QR Code, поэтому доверие к полезной нагрузке — ответственность потребителя, а не кодировщика. Ограничивайте длину полезной нагрузки перед кодированием, чтобы ограничить размер матрицы и избежать отказа в обслуживании из-за чрезмерно большого символа. Парсер GS1 отклоняет некорректные идентификаторы применения (Application Identifiers), что устраняет одну поверхность для инъекций. Он не проверяет смысловое содержимое допустимых полей. Считайте декодированные данные штрихкода недоверенным вводом везде, где они снова попадают в приложение.

Соответствие требованиям

Утверждение	Стандарт	Ссылка
Символы QR Code следуют спецификации матричной символики QR Code.	ISO/IEC 18004	Символика QR Code
Символы Data Matrix следуют спецификации символики Data Matrix.	ISO/IEC 16022	Символика Data Matrix
Символы Code 128 следуют спецификации линейной символики Code 128.	ISO/IEC 15417	Символика Code 128
Строки элементов GS1 разбираются согласно грамматике идентификаторов применения GS1.	GS1 General Specifications (общие спецификации GS1)	Application Identifiers (идентификаторы применения)

На эти стандарты ссылаются по номеру и пункту. Их нет в проверяемом корпусе цитирования, поэтому reference_id не записывается. Движок перефразирует требование и ссылается на источник. За авторитетными правилами кодирования обращайтесь к опубликованным стандартам.

Коммерческий контекст

Core определяет и фиксирует контракты кодировщиков и поставляет распространённые символики. Редакции Pro и Enterprise регистрируют расширенный набор кодировщиков для дополнительных символик штрихкодов под тем же BarcodeEncoderInterface, поэтому коммерческое развёртывание получает больший охват без изменения интерфейса прикладного программирования (API). Core разрешает зарегистрированные кодировщики через BarcodeEncoderRegistry. API контракта идентичен во всех редакциях.

См. также

Контракты: 41 публичный интерфейс (SPI) — обзор интерфейса поставщика сервиса (SPI) и уровней стабильности.
Barcode — реализации символик, зарегистрированные под этими контрактами.
Contracts / Document — PdfDocumentInterface, который отрисовывает закодированную матрицу.
Graphics — слой рисования, отрисовывающий модули штрихкодов.
Exception — BarcodeException, выбрасываемое при некорректном вводе GS1.