estabilidade: Experimental

Gerar códigos de barras GS1 Composite (portador CC-C)

Visão geral

Capacidade de pré-visualização opcional — desativada por padrão. O suporte a GS1 Composite é um recurso experimental e opcional. O único composto entregue é o CC-C (o portador PDF417 completo): o Core registra a capacidade barcode.gs1-composite-cc-c e o pacote Premium (nextpdf/pro) restringe o codificador por trás dela. Apenas com o Core, a capacidade fica registrada, mas seu status é Unavailable, então nada é emitido. CC-A e CC-B ainda não estão disponíveis: uma solicitação para codificar qualquer um deles falha fechada com uma exceção tipada (UnsupportedBarcodeFeature). Este é um limite de escopo documentado, não um defeito.

Um símbolo GS1 Composite emparelha um componente linear (o identificador primário do item) com um componente composto 2D (dados estendidos, como lote ou validade). Esta receita mostra como a capacidade de composto é registrada e resolvida, o que o Core fornece, o que o Premium acrescenta e exatamente onde o suporte para.

Instalação

composer require nextpdf/core:^3

O codificador composto CC-C requer o pacote Premium:

composer require nextpdf/pro

Visão geral conceitual

O NextPDF resolve uma simbologia por meio do registro de capacidades, da mesma forma que o módulo Barcode resolve qualquer codificador. Uma capacidade GS1 Composite é registrada ali:

barcode.gs1-composite-cc-c é registrada em CapabilityRegistry no Core, sob a camada de produto Pro. É o portador PDF417 completo (ISO/IEC 15438) para o componente composto CC-C. O codificador Pro roteia a carga útil pelo codificador PDF417 core canônico. A capacidade é sempre registrada, mas Available apenas quando o Premium está instalado — apenas com o Core, seu status é Unavailable, então ela fica registrada porém inerte (opcional, desativada por padrão).

Nenhuma capacidade CC-A ou CC-B é registrada. Um componente 2D CC-A/CC-B conformante requer a codificação de alto nível base-928 da Cláusula 5 da ISO/IEC 24723 mais um portador específico do componente, e este release não implementa esse caminho, de modo que anunciar uma capacidade CC-A/CC-B nomearia um codificador que não consegue emitir um símbolo decodificável.

Limite de falha fechada — o que ainda não está disponível

CC-A e CC-B intencionalmente não são entregues como simbologias utilizáveis:

CC-A — existem internamente uma primitiva de radix base-928 de baixo nível (Base928Converter, somente codewords) e um construtor de string binária da Cláusula 5, mas a codificação de alto nível CC-A completa da Cláusula 5 da ISO/IEC 24723 e o portador específico de CC-A não estão implementados, então nenhum símbolo CC-A utilizável é produzido. CompositeComponentA::encode() sempre lança a exceção tipada UnsupportedBarcodeFeature.
CC-B — o componente composto de capacidade média também não está implementado; CompositeComponentB::encode() sempre lança UnsupportedBarcodeFeature.

Estes falham fechados: uma solicitação para codificar qualquer um deles levanta uma exceção tipada em vez de emitir um símbolo parcial ou errado. Esta é uma linha de escopo deliberada, não um defeito.

O caminho CC-C entregue segue uma disciplina de codeword-golden: seus codewords gerados são fixados contra um golden e verificados de forma cruzada com um decodificador independente, de modo que um fluxo de codewords CC-C é verificado, não apenas produzido. Nenhuma certificação de ponta a ponta contra a norma GS1 Composite é reivindicada.

Superfície da API

Os símbolos GS1 Composite são resolvidos por meio do registro de capacidades em vez de um novo método de fachada de nível superior:

NextPDF\Support\CapabilityRegistry — a consulta que informa se barcode.gs1-composite-cc-c está Available na edição atual. Use get('barcode.gs1-composite-cc-c')->status para a decisão de disponibilidade; has() apenas informa que a capacidade está registrada (verdadeiro mesmo em instalações somente Core), portanto não é a porta de disponibilidade.
O codificador composto CC-C é fornecido por nextpdf/pro e registrado por trás do mesmo contrato de codificador que a página Contratos / Barcode documenta.
Não há codificador CC-A ou CC-B para chamar. As classes de componente CC-A/CC-B falham fechadas em encode().

Execute composer docs:generate-api-php -- --module=Barcode para obter a tabela de codificadores gerada.

Exemplo de código — Início rápido

Verifique se a capacidade do portador CC-C está disponível antes de depender dela. Apenas com o Core, ela fica registrada, mas Unavailable; com o Premium instalado, fica Available. Condicione ao status, não a has() — has() é verdadeiro em uma instalação somente Core também, porque a capacidade está sempre registrada.

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

Exemplo de código — Produção

Condicione ao status da capacidade e trate os componentes indisponíveis explicitamente. Um símbolo CC-C fiel ou uma recusa clara — nunca um composto errado.

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

Casos extremos e pegadinhas

CC-C precisa do Premium para estar disponível, e é desativado por padrão. O Core registra a capacidade sob a camada Pro; o codificador por trás dela é entregue em nextpdf/pro. Em uma instalação somente Core, a capacidade fica registrada, mas seu status é Unavailable. Condicione a get(...)->status, não a has() — has() é verdadeiro até em uma instalação somente Core, porque a entrada está sempre registrada.
Não há codificador CC-A utilizável. Existe internamente uma primitiva de radix base-928 de baixo nível, mas a codificação de alto nível CC-A completa da Cláusula 5 da ISO/IEC 24723 e o portador específico de CC-A não estão implementados, então nenhum símbolo CC-A é produzido.
CC-A e CC-B falham fechados. O encode() deles sempre lança a exceção tipada UnsupportedBarcodeFeature em vez de emitir um símbolo parcial. Este é um limite de escopo documentado, de propósito.
Os identificadores de aplicação GS1 ainda se aplicam. O componente linear carrega dados estruturados GS1 com o prefixo FNC1, como em Gerar códigos de barras 1D e 2D.
Limite a carga útil. Uma carga útil de composto maior gera um símbolo mais denso. Limite o comprimento da carga útil antes de codificar.

Desempenho

A geração de codewords é linear no comprimento da carga útil; a emissão do portador é linear na área da matriz. Não há etapa de rasterização — cada módulo é um operador de caminho — então a memória permanece plana independentemente do tamanho do símbolo. A receita permanece dentro do orçamento de 1500 ms / 64 MB.

Notas de segurança

Um símbolo composto carrega qualquer carga útil que você passar; trate o valor como não confiável no lado consumidor. Os codificadores codificam bytes e não os autenticam. Limite o comprimento da carga útil antes de codificar para manter o tamanho do símbolo e o trabalho dentro do orçamento.

Conformidade

Declaração	Especificação	Cláusula
O componente composto CC-C entregue usa um portador PDF417.	ISO/IEC 15438 (PDF417)	§5
A codificação de alto nível base-928 do CC-A é o método da Cláusula 5 que este release não implementa.	ISO/IEC 24723 (GS1 Composite)	§5

Esta é uma implementação de pré-visualização experimental e opcional. O Core registra a capacidade barcode.gs1-composite-cc-c sob a camada Pro; o pacote Premium restringe o codificador CC-C, que é desativado por padrão em uma instalação somente Core (status Unavailable). CC-A e CC-B ainda não estão disponíveis — seu encode() falha fechado com a exceção tipada UnsupportedBarcodeFeature. Os codewords CC-C entregues são fixados contra um golden e verificados de forma cruzada com um decodificador independente. Nenhuma disponibilidade geral (GA), conformidade ou certificação de ponta a ponta contra a norma GS1 Composite é reivindicada, e nenhum texto de norma é reproduzido.