Pro редакция

Barcode

Кратко

NextPDF Pro добавляет специализированные 2D- и логистические символики штрихкодов поверх линейных и QR-символик в редакции с открытым исходным кодом. Каждая символика отрисовывается прямо в поверхность страницы PDF как детерминированный поток содержимого.

Доступность и лицензирование

Эта возможность поставляется в составе NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права доступа не загружает классы возможности. Сравните редакции и получите лицензию.

Установка

composer require nextpdf/pro:^3

Кодировщики Pro регистрируют себя через стандартный реестр кодировщиков штрихкодов. Приложения, которые строят собственный реестр, могут повторно зарегистрировать кодировщики Pro явно через опубликованный поставщик услуг.

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

Редакция с открытым исходным кодом охватывает повседневные линейные и QR-символики. NextPDF Pro расширяет тот же реестр специализированными символиками для розничной торговли, логистики, почты и высокоплотного промышленного применения:

Micro QR Code — компактный вариант QR для малой площади этикетки.
DotCode — точечно-матричная символика, рассчитанная на высокоскоростную промышленную маркировку.
Han Xin Code — 2D-символика с встроенной ёмкостью для большого набора текста CJK, согласно ISO/IEC 20830.
JabCode — полихромная 2D-символика с каскадированием нескольких символов.
rMQR — прямоугольный вариант Micro QR для узких, широких этикеток.
GS1 DataBar — семейство розничных и купонных символик GS1.
GS1 Composite (CC-C) — связанная 1D-база плюс высокоплотный 2D-компонент расширения PDF417, несущий данные идентификатора применения GS1. (Кодирование 2D-компонентов расширения CC-A и CC-B не поддерживается в этом выпуске; см. матрицу поддержки.)

Каждый кодировщик создаёт объект данных штрихкода, который отрисовщик страницы преобразует в операторы содержимого PDF. Кодирование детерминировано: один и тот же вход и опции всегда дают один и тот же модульный узор, что сохраняет подписанные и архивированные документы воспроизводимыми.

Углублённый справочник по штрихкодам несёт матрицу поддержки для каждой символики с доказательствами. Для каждой символики и варианта матрица фиксирует одно из трёх состояний: внутрирепозиторная фикстура соответствия проверяет его (Verified), поверхность реализации заявляет его без выделенной фикстуры (Claimed) или он выходит за рамки (Not supported). NextPDF честно сообщает матрицу: вариант, который поставляет кодировщик, но не имеет фикстуры эталонной трассы, остаётся Claimed с примечанием о доработке, а не завышается.

Почему это работает именно так

Каждый кодировщик Pro — чистая функция: один и тот же payload и опции всегда дают одну и ту же модульную матрицу, без скрытого состояния или посеянной случайности. Этот детерминизм — несущее решение. Он позволяет штрихкоду пройти цикл через подписанный или архивированный документ без возмущения байтового потока, поэтому повторная отрисовка никогда не аннулирует подпись. Он также делает соответствие проверяемым: матрица поддержки закрепляет за каждой символикой сохранённую эталонную трассу, сверяемую бит в бит с эталонным файлом. Расширение Core BarcodeEncoderRegistry вместо его форка сохраняет эти гарантии идентичными в открытой и Pro-редакциях.

Проектный контекст: Одни и те же байты каждый раз: воспроизводимые PDF.

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

composer require nextpdf/pro:^3

Публичная поверхность штрихкодов Pro состоит из:

Статической точки входа поставщика услуг, которая регистрирует 2D-кодировщики Pro в реестре кодировщиков штрихкодов (MicroQR, DotCode, HanXin, JabCode, RMQR, GS1DataBar и ключ компонента GS1 Composite CC-C gs1-composite-cc-c). Кодирование 2D-компонентов расширения GS1 Composite CC-A и CC-B не поддерживается в этом выпуске и не регистрируется.
Парсера идентификаторов применения GS1, который принимает как читаемые человеком строки AI, так и URI GS1 Digital Link и создаёт закодированные байтовые последовательности для носителей GS1-128, QR Code и Data Matrix.
Логистического валидатора GS1, который проверяет контрольные цифры, структуру AI, логику дат и обязательные комбинации AI отраслевого профиля.

Полная сформированная таблица сигнатур методов отрисовывается в углублённом справочнике по штрихкодам.

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

use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Pro\Barcode\BarcodeProServiceProvider;

$registry = new BarcodeEncoderRegistry();
BarcodeProServiceProvider::register($registry);
// $registry now resolves the Pro specialty symbologies.

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

use NextPDF\Pro\Barcode\Gs1\Gs1Validator;
use NextPDF\Pro\Barcode\Gs1\Gs1SupplyChainProfile;

$result = Gs1Validator::validate(
    '(01)09521234543213(17)260131(10)ABC123',
    Gs1SupplyChainProfile::NONE,
);

if (! $result->isValid) {
    // Surface findings to your observability pipeline before encoding.
    foreach ($result->findings as $finding) {
        $logger->warning('GS1 validation finding', [
            'rule' => $finding->ruleId,
            'detail' => $finding->message,
        ]);
    }
}

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

Реестр по умолчанию лениво предсвязывает записи кодировщиков Pro и пропускает их через реестр возможностей. Явный вызов BarcodeProServiceProvider::register() — это поддерживаемый резервный вариант, когда приложение составляет собственный реестр без значений по умолчанию.
Повторная регистрация идемпотентна: второй вызов register() заменяет первую привязку, а не вызывает исключение.
Покрытие вариантов GS1 DataBar частично по замыслу. Omnidirectional, Truncated, Stacked, Stacked Omnidirectional и Limited проверены эталоном; Expanded и Expanded Stacked выходят за рамки в этом выпуске. См. матрицу поддержки.
rMQR принимает каждую версию ISO 23941 через проверенный по приложению набор соответствия. Метаданные отслеживания области, предшествующие более позднему расширению диапазона размеров, могут занижать это; матрица поддержки фиксирует проверенную в коде реальность.

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

Стоимость кодирования масштабируется с длиной полезной нагрузки и целевым размером символа. Каждая символика размещает свой символ за один проход без переразметки. Каскады из нескольких символов JabCode масштабируются с числом символов (1–61). Кодирование держит модульную матрицу в памяти; крупнейшая выбранная версия символа ограничивает стоимость.

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

Кодировщики штрихкодов не выполняют содержимое полезной нагрузки; они кодируют его как данные. Валидация GS1 отклоняет некорректные структуры AI и недействительные контрольные цифры перед кодированием, что не даёт некорректной логистической строке создать сканируемый, но несоответствующий символ. Сами кодировщики не записывают полезную нагрузку в журнал; приложения должны очищать конфиденциальные полезные нагрузки из собственных журналов.

Соответствие

Каждая символика следует своему соответствующему опубликованному стандарту (ISO/IEC 24724 для GS1 DataBar, ISO/IEC 24723 для GS1 Composite, ISO/IEC 23941 для rMQR, ISO/IEC 18004 Annex для Micro QR, ISO/IEC 20830 для Han Xin Code, ISO/IEC 23634 для JabCode, USPS-B-3200 для почтовой символики). Сопоставление соответствия на уровне пунктов с идентификаторами цитирования отрисовывается в углублённом справочнике по штрихкодам.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов выходят за рамки.