стабильность: Экспериментальная

Генерация составных штрихкодов GS1 (носитель CC-C)

Кратко

Подключаемая превью-возможность — по умолчанию ВЫКЛЮЧЕНА. Поддержка GS1 Composite — экспериментальная, подключаемая функция. Единственный поставляемый составной символ — CC-C (полный носитель PDF417): Core регистрирует возможность barcode.gs1-composite-cc-c, а пакет Premium (nextpdf/pro) управляет доступом к кодировщику за ней. Только с Core возможность зарегистрирована, но её статус — Unavailable, поэтому ничего не выдаётся. CC-A и CC-B пока недоступны: запрос на кодирование любого из них отказывает закрытием с типизированным исключением (UnsupportedBarcodeFeature). Это задокументированная граница области действия, а не дефект.

Символ GS1 Composite сочетает линейный компонент (первичный идентификатор товара) с двумерным составным компонентом (расширенные данные, такие как партия или срок годности). Этот рецепт показывает, как составная возможность регистрируется и разрешается, что предоставляет Core, что добавляет Premium и где именно поддержка останавливается.

Установка

composer require nextpdf/core:^3

Составной кодировщик CC-C требует пакета Premium:

composer require nextpdf/pro

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

NextPDF разрешает символику через реестр возможностей, тем же способом, каким модуль Barcode разрешает любой кодировщик. Там зарегистрирована одна возможность GS1 Composite:

barcode.gs1-composite-cc-c зарегистрирована в CapabilityRegistry в Core, под товарным уровнем Pro. Это полный носитель PDF417 (ISO/IEC 15438) для составного компонента CC-C. Кодировщик Pro направляет полезную нагрузку через канонический кодировщик PDF417 ядра. Возможность зарегистрирована всегда, но Available только когда установлен Premium — только с Core её статус Unavailable, поэтому она зарегистрирована, но инертна (подключаемая, по умолчанию ВЫКЛЮЧЕНА).

Возможность CC-A или CC-B не зарегистрирована. Соответствующий двумерный компонент CC-A/CC-B требует высокоуровневого кодирования base-928 по Clause 5 ISO/IEC 24723 плюс носитель, специфичный для компонента, а этот выпуск не реализует такой путь, поэтому объявление возможности CC-A/CC-B назвало бы кодировщик, который не может выдать декодируемый символ.

Граница с отказом закрытием — что пока недоступно

CC-A и CC-B намеренно не поставляются как пригодные символики:

CC-A — низкоуровневый радиксный примитив base-928 (Base928Converter, только кодовые слова) и построитель двоичной строки по Clause 5 существуют внутренне, но полное высокоуровневое кодирование CC-A по Clause 5 ISO/IEC 24723 и специфичный для CC-A носитель не реализованы, поэтому пригодный символ CC-A не производится. CompositeComponentA::encode() всегда выбрасывает типизированное исключение UnsupportedBarcodeFeature.
CC-B — составной компонент средней ёмкости тоже не реализован; CompositeComponentB::encode() всегда выбрасывает UnsupportedBarcodeFeature.

Они отказывают закрытием: запрос на кодирование любого из них вызывает типизированное исключение, а не выдаёт частичный или неверный символ. Это намеренная граница области действия, а не дефект.

Поставляемый путь CC-C следует дисциплине эталонных кодовых слов: его сгенерированные кодовые слова закреплены относительно эталона и перекрёстно проверены независимым декодером, поэтому поток кодовых слов CC-C проверен, а не просто произведён. Сквозная сертификация относительно стандарта GS1 Composite не заявляется.

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

Символы GS1 Composite разрешаются через реестр возможностей, а не через новый метод фасада верхнего уровня:

NextPDF\Support\CapabilityRegistry — поиск, который сообщает, доступна ли (Available) barcode.gs1-composite-cc-c в текущей редакции. Используйте get('barcode.gs1-composite-cc-c')->status для решения о доступности; has() лишь сообщает, что возможность зарегистрирована (true даже на установках только с Core), поэтому это не затвор доступности.
Составной кодировщик CC-C предоставляется nextpdf/pro и регистрируется за тем же контрактом кодировщика, который описывает страница Contracts / Barcode.
Кодировщика CC-A или CC-B для вызова нет. Классы компонентов CC-A/CC-B отказывают закрытием в encode().

Выполните composer docs:generate-api-php -- --module=Barcode для сгенерированной таблицы кодировщиков.

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

Проверьте, что возможность носителя CC-C доступна, прежде чем на неё полагаться. Только с Core она зарегистрирована, но Unavailable; с установленным Premium она Available. Привязывайтесь к статусу, а не к has() — has() истинно и на установке только с Core, потому что возможность регистрируется всегда.

<?php

declare(strict_types=1);

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

use NextPDF\Support\CapabilityRegistry;
use NextPDF\Support\CapabilityStatus;

$registry = CapabilityRegistry::getInstance();

$capability = $registry->get('barcode.gs1-composite-cc-c');

if ($capability->status === CapabilityStatus::Available) {
    echo "CC-C composite carrier is available (Premium present)\n";
} else {
    echo "CC-C composite carrier needs nextpdf/pro\n";
}

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

Привязывайтесь к статусу возможности и явно обрабатывайте недоступные компоненты. Точный символ CC-C или ясный отказ — но никогда неверный составной символ.

<?php

declare(strict_types=1);

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

use NextPDF\Support\CapabilityRegistry;
use NextPDF\Support\CapabilityStatus;

final readonly class CompositeLabelService
{
    public function __construct(private CapabilityRegistry $registry) {}

    /**
     * Assert that the only shipped GS1 Composite (CC-C) is available before use.
     *
     * The capability is opt-in and default-OFF: on a Core-only install it is
     * registered but its status is Unavailable, so check the status — not has().
     */
    public function assertCompositeAvailable(): void
    {
        $status = $this->registry->get('barcode.gs1-composite-cc-c')->status;

        if ($status !== CapabilityStatus::Available) {
            // Core-only install. The CC-C encoder needs Premium. Fail fast with
            // a clear upgrade message rather than emitting a degraded symbol.
            throw new \RuntimeException(
                'GS1 Composite CC-C requires nextpdf/pro.',
            );
        }
    }

    // CC-A and CC-B are NOT yet available. Their component classes fail closed:
    // calling encode() always throws NextPDF\Pro\Barcode\Gs1Composite\
    // UnsupportedBarcodeFeature. There is no runnable CC-A/CC-B encode path —
    // CC-C is the only shipped GS1 Composite symbology. Do not call encode() on
    // CC-A/CC-B expecting a symbol.
    public function note(): string
    {
        return 'CC-A and CC-B are not available; use CC-C.';
    }
}

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

CC-C требует Premium, чтобы быть доступным, и по умолчанию ВЫКЛЮЧЕН. Core регистрирует возможность под уровнем Pro; кодировщик за ней поставляется в nextpdf/pro. На установке только с Core возможность зарегистрирована, но её статус Unavailable. Привязывайтесь к get(...)->status, а не к has() — has() истинно даже только с Core, потому что запись регистрируется всегда.
Пригодного кодировщика CC-A нет. Низкоуровневый радиксный примитив base-928 существует внутренне, но полное высокоуровневое кодирование CC-A по Clause 5 ISO/IEC 24723 и специфичный для CC-A носитель не реализованы, поэтому символ CC-A не производится.
CC-A и CC-B отказывают закрытием. Их encode() всегда выбрасывает типизированное исключение UnsupportedBarcodeFeature, а не выдаёт частичный символ. Это задокументированная граница области действия, намеренно.
Идентификаторы применения GS1 по-прежнему применяются. Линейный компонент несёт структурированные по GS1 данные с префиксом FNC1, как в Генерация 1D- и 2D-штрихкодов.
Ограничивайте полезную нагрузку. Большая составная полезная нагрузка даёт более плотный символ. Ограничивайте длину полезной нагрузки перед кодированием.

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

Генерация кодовых слов линейна по длине полезной нагрузки; выдача носителя линейна по площади матрицы. Шага растеризации нет — каждый модуль — это оператор пути — поэтому память остаётся плоской независимо от размера символа. Рецепт остаётся в пределах бюджета 1500 мс / 64 МБ.

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

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

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

Утверждение	Спецификация	Раздел
Поставляемый составной компонент CC-C использует носитель PDF417.	ISO/IEC 15438 (PDF417)	§5
Высокоуровневое кодирование base-928 для CC-A — это метод Clause 5, который этот выпуск не реализует.	ISO/IEC 24723 (GS1 Composite)	§5

Это экспериментальная подключаемая превью-реализация. Core регистрирует возможность barcode.gs1-composite-cc-c под уровнем Pro; пакет Premium управляет доступом к кодировщику CC-C, который по умолчанию ВЫКЛЮЧЕН на установке только с Core (статус Unavailable). CC-A и CC-B пока недоступны — их encode() отказывает закрытием с типизированным исключением UnsupportedBarcodeFeature. Поставляемые кодовые слова CC-C закреплены относительно эталона и перекрёстно проверены независимым декодером. Никакой GA, соответствие или сквозная сертификация относительно стандарта GS1 Composite не заявляются, и текст стандартов не воспроизводится.