Barcode — глубокий справочник

Коротко о главном

Поверхность штрихкодов NextPDF Pro добавляет специализированные 2D- и снабженческие символики поверх модуля Core barcode. Она поставляет шесть разрешаемых через реестр 2D-кодировщиков (Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), один кодировщик 2D-компонента GS1 Composite (CC-C), 1D-кодировщик USPS Intelligent Mail и парсер GS1 Application Identifier вместе с валидатором цепочки поставок. Кодирование детерминировано: одни и те же полезная нагрузка и опции всегда дают идентичную матрицу модулей. Эта страница описывает публичный API, контракт поведения, режимы отказа и доказательства соответствия по каждой символике.

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

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

composer require nextpdf/pro:^3

Каждая символика привязывает собственное имя возможности в лицензионном конверте: barcode.microqr, barcode.dotcode, barcode.hanxin, barcode.jabcode, barcode.rmqr, barcode.gs1databar и barcode.gs1-composite-cc-c. Когда возможность не лицензирована, реестр не разрешает этот кодировщик. Кодирование полного символа GS1 Composite CC-A и CC-B не поддерживается (см. таблицу статуса поддержки), поэтому ключ barcode.gs1-composite-cc-a или barcode.gs1-composite-cc-b не регистрируется.

Публичная поверхность API

Ключи реестра берутся из значений вариантов Core NextPDF\Barcode\Barcode2DType плюс литеральный ключ gs1-composite-cc-c. Для разрешаемых через реестр кодировщиков стабильным контрактом является ключ реестра, а не FQCN кодировщика.

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается с	Примечания
BarcodeProServiceProvider::register()	BarcodeEncoderRegistry $registry	Привязывает все семь ключей реестра Pro	void	—	Статический; идемпотентный — второй вызов заменяет первую привязку
MicroQrEncoder::encode()	$data; опции ecLevel ('L', 'M', 'Q'; по умолчанию 'L'), version (1–4 или null), mask (0–3 или null)	Автоматически выбирает наименьшую подходящую версию M1–M4	Barcode2DData	InvalidArgumentException	Неподдерживаемое 'H' МОЛЧА приводится к 'L' (вызывающие стороны, которым нужен отказ в закрытое состояние при выборе EC, должны предварительно проверять); M1 игнорирует ecLevel
DotCodeEncoder::encode()	$data; опции gs1 (bool, по умолчанию false), columns (int), rows (int), ratio (float, по умолчанию 1.5)	Автоматический размер сетки при соотношении ширина:высота 1.5	Barcode2DData	InvalidArgumentException	Размеры сетки можно задать принудительно по каждой оси
HanXinEncoder::encode()	$data; опции ecLevel (0–3, по умолчанию 1), version (1–84, по умолчанию авто)	Наименьшая подходящая версия	Barcode2DData	InvalidArgumentException	Текстовые режимы GB 2312 регионов 1/2 согласно ISO/IEC 20830
JabCodeEncoder::encode()	$data; опции colors (4, 8, 16, 32, 64, 128, 256; по умолчанию 8), eccLevel (0–10, по умолчанию 3), symbolNumber (1–61, по умолчанию 1), symbolVersions, symbolPositions, symbolEccLevels	Один 8-цветный символ	BarcodeColorData	InvalidArgumentException, JabCodeEncodingException	Полихромная матрица модулей с палитрой
RmqrEncoder::encode()	$data; опции ecLevel (RmqrConstants::EC_M по умолчанию или EC_H), version (например 'R7x43', по умолчанию авто)	Наименьшая подходящая из 32 версий ISO/IEC 23941	Barcode2DData	InvalidArgumentException	Отклоняет полезные нагрузки, превышающие ёмкость; никогда не обрезает
Gs1DataBarEncoder::encode()	$data; опции variant (Gs1DataBarVariant, по умолчанию OMNIDIRECTIONAL), linkage (bool, по умолчанию false), height (int, по умолчанию минимум варианта; по строке для Expanded Stacked), segmentsPerRow (int, по умолчанию 4; только Expanded Stacked)	Кодирует вход GTIN (семейство §5/§6) или строку элементов GS1 AI (семейство §7)	Barcode2DData	InvalidArgumentException; InvalidSymbolStructureException	Кодируются все семь вариантов ISO/IEC 24724, приложение J
Gs1DataBarVariant	—	isImplemented() возвращает true для всех семи вариантов	перечисление (7 вариантов)	—	minimumHeightX() и defaultHeightX() согласно приложению J
ImbEncoder::encode()	string $code (20, 25, 29 или 31 цифра)	65 четырёхуровневых штрихов	BarcodeData	InvalidArgumentException	Интерфейс 1D-кодировщика; не ключ 2D-реестра
ImbEncoder::encodeToString()	string $code	Состояния штрихов в виде строки T/A/D/F	string	InvalidArgumentException	Для сверки с эталонными векторами USPS
Gs1DataParser::parse()	string $data	Автоматически распознаёт URI Digital Link, иначе формат (AI)value	Gs1ParsedData	InvalidArgumentException	Реализует контракт Core Gs1DataParserInterface
Gs1DataParser::parseDigitalLink()	string $uri	Разбирает URI GS1 Digital Link	Gs1ParsedData	InvalidArgumentException	—
Gs1DataParser::encodeForCode128() / ::encodeForQrCode() / ::encodeForDataMatrix()	object $parsed	Последовательность байтов носителя с соглашением FNC1 этого носителя	string	—	Ожидает экземпляр Gs1ParsedData
Gs1DataParser::validateAI()	string $ai, string $value	Структурная проверка одного значения AI	bool	—	—
Gs1Validator::validate()	string $barcodeData, Gs1SupplyChainProfile $profile (по умолчанию NONE)	Статический быстрый путь поверх run()	Gs1ValidationResult	—	Ошибки разбора становятся находками, а не исключениями
Gs1Validator::run()	как у validate()	Разбор, контрольные цифры, даты, перекрёстные правила AI, профиль	Gs1ValidationResult	—	Путь экземпляра; конструктор принимает внедрённый парсер
Gs1SupplyChainProfile	—	NONE пропускает правила профиля	перечисление (5 вариантов)	—	RETAIL, FOOD, PHARMA, LOGISTICS, NONE; requiredAIs(), recommendedAIs(), primaryIdentifiers()
Gs1ValidationResult	—	Находки разбиваются по серьёзности при конструировании	readonly-класс	—	isValid, findings, errors, warnings, infos, parsedData; passes(), fails(), totalFindings()
Gs1ValidationFinding / Gs1FindingSeverity	—	severity, ruleId, message, необязательные ai и suggestion	readonly-класс / перечисление	—	Уровни серьёзности: Error, Warning, Info
CompositeComponentA::codewordsFor()	string $data	Кодирование двоичной строки общего назначения §5, преобразование по основанию 928, самопроверка кругового прохода	list<int> (каждое 0–927)	InvalidArgumentException	Передайте в linkFor() или во внешний рендерер носителя CC-A
CompositeComponentA::encode()	игнорируется	Отказывает в рендеринге полного символа CC-A	—	UnsupportedBarcodeFeature (всегда)	Отказ в закрытое состояние; см. Граничные случаи
CompositeComponentB::encode()	игнорируется	Отказывает в 2D-кодировании CC-B	—	UnsupportedBarcodeFeature (всегда)	linkFor() остаётся доступным (CCSI 901)
CompositeComponentC::encode()	$data; опции передаются носителю PDF417; carrierType (по умолчанию GS1_128)	Полный носитель PDF417 с ведущим кодовым словом CCSI 920	Barcode2DData	BarcodeException; CompositeLinkageException	Допустим только носитель GS1_128
CompositeComponent{A,B,C}::linkFor()	string $carrierId, array $codewords, CompositeCarrierType $carrierType	Сопоставляет кодовые слова компонента с 1D-носителем	CompositeLinkage	CompositeLinkageException	Обеспечивает допустимость носителя и ёмкость
CompositeVariant / CompositeCarrierType	—	CC_A, CC_B, CC_C; GS1_DATABAR, GS1_128	перечисления	—	maxCodewords(), ccsi(), allowedCarriers(), usesFullPdf417()

Сигнатуры точек входа

public static function register(BarcodeEncoderRegistry $registry): void

public function encode(string $data, array $options = []): Barcode2DData

public static function validate(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function run(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function parse(string $data): Gs1ParsedData
public function parseDigitalLink(string $uri): Gs1ParsedData
public function encodeForCode128(object $parsed): string
public function encodeForQrCode(object $parsed): string
public function encodeForDataMatrix(object $parsed): string
public function validateAI(string $ai, string $value): bool

public function codewordsFor(string $data): array

Контракт поведения

Разрешение через реестр

Фабрика реестра Core по умолчанию предварительно привязывает кодировщики Pro как ленивые, лицензируемые по возможности записи. BarcodeProServiceProvider::register() — поддерживаемый резервный вариант для приложений, которые составляют реестр без значений по умолчанию, например для интеграций с фреймворками с собственным контейнером. Каждый кодировщик преобразует строковую полезную нагрузку и опции для конкретной символики в объект данных штрихкода, который рендерер страницы превращает в операторы содержимого PDF.

Разбор и валидация GS1

Gs1DataParser принимает читаемые человеком строки AI ((01)09521234543213(17)260131) и URI GS1 Digital Link. Он порождает закодированные последовательности байтов для носителей GS1-128, QR Code и Data Matrix, применяя соглашение FNC1 и разделителя групп каждого носителя. Gs1Validator выполняет конвейер из пяти шагов: разбор, контрольные цифры (GTIN, SSCC), логика дат, перекрёстные правила AI и обязательные AI отраслевого профиля. Ошибка разбора даёт недопустимый результат с находками; исключение не бросается. Находки разбиваются по серьёзности на ошибки, предупреждения и информационные сообщения.

Диспетчеризация вариантов GS1 DataBar

Gs1DataBarEncoder::encode() диспетчеризует все семь вариантов ISO/IEC 24724:2011, приложение J, через один контракт опций. Omnidirectional, Truncated, Stacked и Stacked Omnidirectional используют общую алгебру ширины элементов §5 с контрольным знаком по модулю 79. Limited использует собственную алгебру символьных знаков §6 с контрольным знаком по модулю 89. Expanded и Expanded Stacked используют алгебру §7 (17,4): трёхрежимный автомат сжатия §7.2.5.5 (числовой, буквенно-цифровой и ISO/IEC 646) плюс контрольный знак по модулю 211 (§7.2.6). Семейство §5/§6 принимает 14-значный GTIN-14 с контрольной цифрой по модулю 10 или 13-значную идентификацию товара. Семейство §7 принимает сырую строку элементов GS1 AI (цифры, буквы, подмножество пунктуации ISO/IEC 646, FNC1 как байт 0x1D). Опция linkage устанавливает флаг связывания 2D-компонента для использования в качестве линейного компонента символа GS1 Composite.

Компоненты GS1 Composite

CC-C порождает полный 2D-расширенный компонент поверх полного носителя PDF417, вставляя обязательное кодовое слово CCSI 920 как ведущее кодовое слово данных (ISO/IEC 24723:2010 §5.4). CC-A генерирует соответствующие кодовые слова данных по основанию 928 через codewordsFor() с самопроверкой кругового прохода кодирование–декодирование в закрытое состояние, но отказывает в рендеринге полного символа. CC-B полностью отказывает в 2D-кодировании. linkFor() сопоставляет кодовые слова компонента с 1D-носителем как значение CompositeLinkage, обеспечивая допустимость носителя и ёмкость.

Граничные случаи и режимы отказа

• Каждый кодировщик отклоняет пустую полезную нагрузку с InvalidArgumentException.
• Micro QR: запрос неподдерживаемого уровня коррекции ошибок H МОЛЧА приводится к L, а не завершается ошибкой (предварительно проверяйте опции, если требуется отказ в закрытое состояние при выборе EC), поскольку ISO/IEC 18004 определяет для символов Micro QR только L, M и Q.
• rMQR: уровень коррекции ошибок должен быть M или H; полезная нагрузка, превышающая ёмкость 32 версий, отклоняется, а не обрезается.
• JabCode: количество цветов вне поддерживаемого набора степеней двойки, уровень ECC вне 0–10 или количество символов вне 1–61 отклоняется; последующие ошибки кодирования порождают JabCodeEncodingException.
• GS1 DataBar: семейство §5/§6 проверяет контрольную цифру GTIN по модулю 10, а Limited ограничивает индикаторную цифру значениями 0 или 1. Семейство §7 отклоняет некодируемые символы и завершающие или сдвоенные разделители FNC1. Expanded Stacked отклоняет нечётное количество символьных знаков в строке и высоту строки ниже минимума 34X. Самопроверки внутренней структуры завершаются с InvalidSymbolStructureException, а не выдают некорректный символ.
• GS1 Composite: encode() у CC-A и CC-B всегда бросает UnsupportedBarcodeFeature (отказ в закрытое состояние). CC-C бросает BarcodeException при пустых данных или переполнении ёмкости PDF417 (более 925 кодовых слов) и CompositeLinkageException для недопустимого носителя.
• Валидация GS1 помечает некорректную структуру AI и неверные контрольные цифры до кодирования; недопустимая строка цепочки поставок никогда не порождает сканируемый соответствующий символ.
• IMB принимает только вход из 20, 25, 29 или 31 цифры.
• Кодирование штрихкодов не выполняет криптографии. Нет поведения, специфичного для режима FIPS; кодировщики работают одинаково независимо от профиля FIPS.

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

NextPDF реализует эти символики в соответствии с опубликованными стандартами, приведёнными ниже, и фиксирует трассировки эталонов в своём наборе тестов. Утверждения на этой странице — это заявления о возможностях: поддержка не есть соответствие, а соответствие не есть сертификация. NextPDF не имеет сертификации по символикам. Якоря пунктов перефразированы из исходного кода продукта и его фикстур соответствия; корпус движка соответствия не охватывает стандарты символик штрихкодов, поэтому приведённые ниже якоря обоснованы продуктом без идентификаторов фрагментов.

Поверхность	Стандарт	Якорь пункта (перефразировано)
Алгебра ширины элементов GS1 DataBar	ISO/IEC 24724:2011	§5.2 структура символьного знака; приложение F.1 проработанный пример (Omnidirectional); приложение F.2 (Limited); приложение F.3 (Expanded)
Раскладки со стопкой GS1 DataBar	ISO/IEC 24724:2011	§5.4 Stacked; §5.5 Stacked Omnidirectional; §7.2.8 разбиение на строки и разделители Expanded Stacked
Кодирование GS1 DataBar Expanded	ISO/IEC 24724:2011	§7.2.5.5 трёхрежимный автомат сжатия; §7.2.6 контрольный знак по модулю 211
Связывание GS1 Composite и CC-C	ISO/IEC 24723:2010	§5.4 семантика кодового слова CCSI; §5.1 допустимость носителя
Кодовые слова GS1 Composite CC-A	ISO/IEC 24723:2010	§5 кодирование двоичной строки общего назначения с преобразованием по основанию 928
Структура символа rMQR	ISO/IEC 23941:2022	§6.3.2 таблица 1 размеры версий; §7.8.2 фиксированная маска; эталон format-info приложений C / I
Micro QR	ISO/IEC 18004	ёмкость Micro QR M1–M4 и format-info
Han Xin Code	ISO/IEC 20830:2021	структура символа; паттерны поиска и выравнивания; режимы GB 2312 регионов 1/2; ECC Рида–Соломона; маскирование
JabCode	ISO/IEC 23634	структура символа, цвета и ECC
Почтовая символика	USPS-B-3200	структура полей Intelligent Mail Barcode

Статус поддержки по символикам

Вариант получает статус Verified, когда его прорабатывает фикстура в pro/tests/**, желательно трассировка эталона, привязанная к опубликованному проработанному примеру. Поставленный вариант без выделенной фикстуры остаётся Claimed. Вариант без кодировщика — Not supported.

Символика / вариант	Статус	Доказательство (путь к тесту)	Примечания
Micro QR (M1–M4)	Verified	pro/tests/Unit/Barcode/MicroQrEncoderTest.php	Модульный уровень; фикстура с трассировкой эталона из проработанного примера — отслеживаемая доработка
DotCode	Verified	pro/tests/Unit/Barcode/DotCodeEncoderTest.php; DotCodeGfArithmeticTest.php	Охвачена арифметика поля Галуа; нет кругового прохода с декодером вендора
Han Xin Code	Verified	pro/tests/Unit/Barcode/HanXinEncoderTest.php; HanXinRsEncodingTest.php	Путь кодирования Рида–Соломона прорабатывается явно
JabCode (1–61 символов, 4–256 цветов, ECC 0–10)	Verified	pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php (+ 11 покомпонентных наборов в том же каталоге)	Каскад из нескольких символов и диапазон ECC прорабатываются; нет кругового прохода с декодером вендора
USPS Intelligent Mail Barcode	Verified	pro/tests/Unit/Barcode/ImbEncoderTest.php; ImbRoutingCodeTest.php	Прорабатываются маршрутный код и валидация длины 20/25/29/31 цифр
rMQR — все 32 версии ISO/IEC 23941	Verified	pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php; RmqrAnnexCFormatInfoTest.php; pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php	Пары версия/EC проверены по таблице 1 ISO/IEC 23941; эталонные значения format-info из приложений C / I
GS1 DataBar — Omnidirectional / Truncated	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php	Байт-равно проработанному примеру приложения F.1; Truncated использует то же кодирование при уменьшенной высоте
GS1 DataBar — Stacked / Stacked Omnidirectional	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php	Разбиение на строки выведено из трассировки приложения F.1; построение разделителей согласно §5.4 и §5.5
GS1 DataBar — Limited	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php; pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php	Байт-равно проработанному примеру приложения F.2 (товар 00098765432105)
GS1 DataBar — Expanded	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php; pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php	Байт-равно проработанному примеру приложения F.3 ((10)12A); круговой проход с независимыми декодерами zxing-cpp и ZBar
GS1 DataBar — Expanded Stacked	Verified	pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php (случаи со стопкой); интеграционный круговой проход выше	Тот же конвейер данных, что и у однострочного Expanded; проверяются разбиение на строки и разделители §7.2.8
GS1 Composite — CC-C (носитель PDF417)	Verified	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php; CompositeRoundtripTest.php; CompositeLinkageTest.php	Охвачены кодовое слово CCSI 920 и взаимодействие флага связывания
GS1 Composite — CC-A	Partial	pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php; pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php	Генерация кодовых слов Verified (основание 928, самопроверка кругового прохода); рендеринг полного символа не поддерживается — encode() отказывает в закрытое состояние
GS1 Composite — CC-B	Not supported	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php (утверждает отказ в закрытое состояние)	Нет 2D-кодирования; помощник связывания (CCSI 901) остаётся доступным
Парсер GS1 AI	Verified	pro/tests/Unit/Barcode/Gs1DataParserTest.php; Gs1DataParserFnc1Test.php	Прорабатываются оба формата ввода и все три выхода последовательностей байтов носителей
Валидатор цепочки поставок GS1	Verified	pro/tests/Unit/Barcode/Gs1ValidatorTest.php; Gs1ValidatorCrossAiTest.php; pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php	Прорабатываются контрольные цифры, обязательные перекрёстные комбинации AI и логика дат

Заметки по разработке

• Якоря доказательств на этой странице — это пути к тестам в pro/tests/**; репозиторий не поставляет каталог examples/ для этого модуля.
• Семь имён возможностей, перечисленных в разделе «Доступность и лицензирование», — это ключи, которые привязывает поставщик служб. Кодировщик IMB конструируется напрямую и не имеет ключа реестра.
• CC-A выдаёт только метод кодирования общего назначения; специфичные для приложений сжатые методы — это документированный остаток по плотности, а не пробел в корректности.

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

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

См. также

• Обзор возможности Barcode (NextPDF Pro)
• Chart — глубокий справочник
• Модуль Core barcode