Barcode: кодировщики линейных и матричных символик

Обзор

Модуль Barcode предоставляет слой реализации символик. Он кодирует линейные символики (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, почтовые коды) и матричные символики (QR Code, Data Matrix, PDF417), вычисляет коррекцию ошибок и регистрирует каждый кодировщик через контракты штрихкодов, чтобы компонент записи документа мог отрисовать результат. Определения контрактов вынесены на отдельную страницу. См. примечание ниже.

Одна каноническая страница на тему. Интерфейсы, которые реализует кодировщик (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) описаны на Contracts / Barcode. На этой странице описаны конкретные кодировщики, реализующие эти контракты. Страницы дополняют друг друга, а не дублируют: страница контрактов описывает интерфейс поставщика услуг (SPI), а эта страница — символики.

Установка

composer require nextpdf/core:^3

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

Кодировщик штрихкода преобразует строку полезной нагрузки в двумерную (2D) матрицу модулей или одномерную (1D) последовательность штрихов, которую компонент записи отрисовывает как графику Portable Document Format (PDF). Этот модуль предоставляет конкретные кодировщики.

Barcode1D — линейный движок. BarcodeType перечисляет поддерживаемые линейные символики: Code 39 (с контрольной суммой и без неё), Code 93, семейство Code 128, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved и Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB) и MSI. generate() возвращает объект-значение BarcodeData, описывающий рисунок штрихов.

2D-кодировщики — QrEncoder, DataMatrixEncoder и Pdf417Encoder — реализуют BarcodeEncoderInterface и возвращают матрицу Barcode2DData. Barcode2DType перечисляет матричные символики, распознаваемые движком, включая QR Code, Data Matrix и PDF417. Дополнительные символики, такие как Micro QR, rMQR, GS1 DataBar и Han Xin, перечислены для маршрутизации через реестр. Доступный для каждой символики набор кодировщиков зависит от редакции. Коррекция ошибок для матриц вычисляется над полем Галуа. GaloisField и GaloisFieldPrime обеспечивают арифметику Рида — Соломона, общую для кодировщиков QR, Data Matrix и PDF417.

BarcodeEncoderRegistry — механизм поиска. Он реализует PHP Standards Recommendation 11 (PSR-11) ContainerInterface, обеспечивает регистрацию по умолчанию через createDefault() и сопоставляет символику с её кодировщиком с помощью resolve(). Прикладной код редко обращается к кодировщику напрямую. Высокоуровневый фасад Document::write1DBarcode() / write2DBarcode() указывает символику, а реестр предоставляет кодировщик. Движок 1D имеет статус @since 1.0.0. Кодировщики 2D имеют статус @since 1.3.0. Реестр имеет статус @since 3.0.0.

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

Класс	Ключевые члены	Роль
`Barcode1D`	`generate(string $code, BarcodeType $type): BarcodeData`	Кодировщик линейных символик (`@since 1.0.0`)
`QrEncoder`	`encode(string $data, array $options = []): Barcode2DData`	Кодировщик QR Code (`@since 1.3.0`)
`DataMatrixEncoder`	`encode(string $data, array $options = []): Barcode2DData`	Кодировщик Data Matrix (`@since 1.3.0`)
`Pdf417Encoder`	`encode(string $data, array $options = []): Barcode2DData`	Кодировщик PDF417 (`@since 1.3.0`)
`BarcodeEncoderRegistry`	`createDefault()`, `register()`, `resolve()`, `has()`, `get()`, `registered()`	Реестр кодировщиков PSR-11 (`@since 3.0.0`)
`BarcodeType` / `Barcode2DType`	значения перечисления	Перечисления поддерживаемых символик
`GaloisField` / `GaloisFieldPrime`	арифметика конечного поля	Коррекция ошибок Рида — Соломона

Запустите composer docs:generate-api-php -- --module=Barcode, чтобы получить полную таблицу PHPDoc.

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

Источник: examples/10-barcodes.php. Фасад получает кодировщик для запрошенной символики через реестр.

<?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');

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

Получите 2D-кодировщик напрямую из реестра и ограничьте полезную нагрузку перед кодированием.

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

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

Полезная нагрузка для линейной символики, не соответствующая набору символов символики или правилу контрольной цифры, вызывает BarcodeException. EAN/UPC вычисляют и добавляют контрольную цифру. Не добавляйте её заранее.
Массив $options для 2D зависит от символики: например, в QR это уровень коррекции ошибок. Большинство кодировщиков игнорирует неизвестные ключи. Сверяйте каждый ключ с документацией конкретного кодировщика.
Barcode2DType перечисляет больше символик, чем кодировщиков доступно в редакции core. BarcodeEncoderRegistry::resolve() выбрасывает исключение для незарегистрированной символики, а не возвращает заглушку.
Зарегистрированные кодировщики являются общими экземплярами. Не храните в них состояние, кроме конфигурации, переданной в конструкторе. Состояние, зависящее от вызова, нарушает параллельную отрисовку.
Слишком длинная полезная нагрузка создаёт более плотную и крупную матрицу. Ограничивайте длину полезной нагрузки перед кодированием, чтобы избежать отказа в обслуживании из-за размера символа.

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

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

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

Полезная нагрузка штрихкодов часто поступает из недоверенных источников: отсканированный унифицированный указатель ресурса (URL), серийный номер или код отслеживания. Кодировщики кодируют байты и не интерпретируют их. QR Code, кодирующий вредоносный URL, всё равно остаётся корректным QR Code, поэтому за оценку доверия к полезной нагрузке отвечает потребитель. Ограничивайте длину полезной нагрузки перед кодированием, чтобы держать размер матрицы, объём работы и размер вывода в пределах бюджета. Любые данные, декодированные из штрихкода в другом месте, считайте недоверенным вводом при повторном попадании в приложение. См. модель угроз движка в /modules/core/security/.

Соответствие стандартам

Утверждение	Стандарт	Ссылка
Символы QR Code соответствуют спецификации матричной символики QR Code.	ISO/IEC 18004	символика QR Code
Символы Data Matrix соответствуют спецификации символики Data Matrix.	ISO/IEC 16022	символика Data Matrix
Символы PDF417 соответствуют спецификации символики PDF417.	ISO/IEC 15438	символика PDF417
Символы Code 128 соответствуют спецификации линейной символики Code 128.	ISO/IEC 15417	символика Code 128
Символы EAN/UPC соответствуют спецификации символики EAN/UPC.	ISO/IEC 15420	символика EAN/UPC

Эти стандарты символик отсутствуют в проверяемом корпусе цитирования, поэтому reference_id не записывается. На этой странице требование перефразировано, а источник указан по номеру и пункту. Авторитетные правила кодирования см. в опубликованных стандартах. Кодировщики проверяются в tests/Unit/Barcode/. Корректность относительно спецификаций символик — зона ответственности набора тестов, а не утверждение о сквозном соответствии PDF.

См. также

Contracts / Barcode — интерфейсы кодировщиков, которые реализуют эти классы (SPI).
Модуль Graphics — слой рисования, отрисовывающий закодированную матрицу.
Модуль Document — высокоуровневый фасад write1DBarcode() / write2DBarcode().
Обзор соответствия стандартам
Модель безопасности движка