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

De un vistazo

Capacidad de vista previa opcional — DESACTIVADA por defecto. La compatibilidad con GS1 Composite es una característica experimental y opcional. El único compuesto incluido es CC-C (el portador PDF417 completo): Core registra la capacidad barcode.gs1-composite-cc-c y el paquete Premium (nextpdf/pro) restringe el codificador detrás de ella. Solo con Core, la capacidad está registrada pero su estado es Unavailable, por lo que no se emite nada. CC-A y CC-B aún no están disponibles: una solicitud para codificar cualquiera de ellos se cierra de forma segura con una excepción tipada (UnsupportedBarcodeFeature). Esto es un límite de alcance documentado, no un defecto.

Un símbolo GS1 Composite empareja un componente lineal (el identificador principal del artículo) con un componente compuesto 2D (datos extendidos como un lote o una caducidad). Esta receta muestra cómo se registra y se resuelve la capacidad compuesta, qué proporciona Core, qué añade Premium y exactamente dónde se detiene la compatibilidad.

Instalación

composer require nextpdf/core:^3

El codificador compuesto CC-C requiere el paquete Premium:

composer require nextpdf/pro

Panorama conceptual

NextPDF resuelve una simbología a través del registro de capacidades, de la misma manera que el módulo Barcode resuelve cualquier codificador. Allí se registra una capacidad GS1 Composite:

• barcode.gs1-composite-cc-c está registrado en CapabilityRegistry en Core, bajo el nivel de producto Pro. Es el portador PDF417 completo (ISO/IEC 15438) para el componente compuesto CC-C. El codificador Pro enruta la carga útil a través del codificador PDF417 canónico del core. La capacidad está siempre registrada pero Available solo cuando Premium está instalado: solo con Core su estado es Unavailable, por lo que está registrada pero inerte (opcional, DESACTIVADA por defecto).

No se registra ninguna capacidad CC-A o CC-B. Un componente 2D CC-A/CC-B conforme requiere la codificación de alto nivel base-928 de la cláusula 5 de ISO/IEC 24723 más un portador específico del componente, y esta versión no implementa esa ruta, por lo que anunciar una capacidad CC-A/CC-B nombraría un codificador que no puede emitir un símbolo decodificable.

Límite de cierre seguro — qué aún no está disponible

CC-A y CC-B intencionadamente no se incluyen como simbologías utilizables:

• CC-A: existen internamente una primitiva de radix base-928 de bajo nivel (Base928Converter, solo palabras de código) y un constructor de cadenas binarias de la cláusula 5, pero la codificación de alto nivel CC-A completa de la cláusula 5 de ISO/IEC 24723 y el portador específico de CC-A no están implementados, por lo que no se produce ningún símbolo CC-A utilizable. CompositeComponentA::encode() siempre lanza la excepción tipada UnsupportedBarcodeFeature.
• CC-B: el componente compuesto de capacidad media tampoco está implementado; CompositeComponentB::encode() siempre lanza UnsupportedBarcodeFeature.

Estos se cierran de forma segura: una solicitud para codificar cualquiera de ellos lanza una excepción tipada en lugar de emitir un símbolo parcial o incorrecto. Esto es una línea de alcance deliberada, no un defecto.

La ruta CC-C incluida sigue una disciplina de golden de palabras de código: sus palabras de código generadas se fijan frente a un golden y se verifican de forma cruzada con un decodificador independiente, de modo que un flujo de palabras de código CC-C se verifica, no solo se produce. No se reclama ninguna certificación de extremo a extremo frente a la norma GS1 Composite.

Superficie de la API

Los símbolos GS1 Composite se resuelven a través del registro de capacidades en lugar de un nuevo método de fachada de nivel superior:

• NextPDF\Support\CapabilityRegistry: la búsqueda que informa de si barcode.gs1-composite-cc-c está Available en la edición actual. Use get('barcode.gs1-composite-cc-c')->status para la decisión de disponibilidad; has() solo informa de que la capacidad está registrada (verdadero incluso en instalaciones solo de Core), por lo que no es la compuerta de disponibilidad.
• El codificador compuesto CC-C lo suministra nextpdf/pro y se registra detrás del mismo contrato de codificador que documenta la página Contratos / Barcode.
• No hay ningún codificador CC-A o CC-B al que llamar. Las clases de componente CC-A/CC-B se cierran de forma segura en encode().

Ejecute composer docs:generate-api-php -- --module=Barcode para obtener la tabla de codificadores generada.

Ejemplo de código — Inicio rápido

Compruebe que la capacidad del portador CC-C está disponible antes de depender de ella. Solo con Core está registrada pero Unavailable; con Premium instalado está Available. Condicione sobre el estado, no sobre has(): has() es verdadero también en una instalación solo de Core, porque la capacidad siempre está 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";
}

Ejemplo de código — Producción

Condicione sobre el estado de la capacidad y trate los componentes no disponibles de forma explícita. Un símbolo CC-C fiel o una negativa clara, nunca un compuesto incorrecto.

<?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 límite y trampas

• CC-C necesita Premium para estar disponible, y está DESACTIVADO por defecto. Core registra la capacidad bajo el nivel Pro; el codificador detrás de ella se incluye en nextpdf/pro. En una instalación solo de Core la capacidad está registrada pero su estado es Unavailable. Condicione sobre get(...)->status, no sobre has(): has() es verdadero incluso en una instalación solo de Core porque la entrada siempre está registrada.
• No hay ningún codificador CC-A utilizable. Existe internamente una primitiva de radix base-928 de bajo nivel, pero la codificación de alto nivel CC-A completa de la cláusula 5 de ISO/IEC 24723 y el portador específico de CC-A no están implementados, por lo que no se produce ningún símbolo CC-A.
• CC-A y CC-B se cierran de forma segura. Su encode() siempre lanza la excepción tipada UnsupportedBarcodeFeature en lugar de emitir un símbolo parcial. Esto es un límite de alcance documentado, a propósito.
• Los identificadores de aplicación GS1 siguen aplicándose. El componente lineal porta datos estructurados según GS1 con el prefijo FNC1, como en Generar códigos de barras 1D y 2D.
• Acote la carga útil. Una carga útil compuesta más grande produce un símbolo más denso. Acote la longitud de la carga útil antes de codificar.

Rendimiento

La generación de palabras de código es lineal en la longitud de la carga útil; la emisión del portador es lineal en el área de la matriz. No hay paso de rasterización —cada módulo es un operador de trazado—, por lo que la memoria se mantiene plana independientemente del tamaño del símbolo. La receta se mantiene dentro del presupuesto de 1500 ms / 64 MB.

Notas de seguridad

Un símbolo compuesto porta cualquier carga útil que usted pase; trate el valor como no confiable en el lado consumidor. Los codificadores codifican bytes y no los autentican. Acote la longitud de la carga útil antes de codificar para mantener el tamaño del símbolo y el trabajo dentro del presupuesto.

Conformidad

Afirmación	Especificación	Cláusula
El componente compuesto CC-C incluido usa un portador PDF417.	ISO/IEC 15438 (PDF417)	§5
La codificación de alto nivel base-928 de CC-A es el método de la cláusula 5 que esta versión no implementa.	ISO/IEC 24723 (GS1 Composite)	§5

Esta es una implementación de vista previa experimental y opcional. Core registra la capacidad barcode.gs1-composite-cc-c bajo el nivel Pro; el paquete Premium restringe el codificador CC-C, que está DESACTIVADO por defecto en una instalación solo de Core (estado Unavailable). CC-A y CC-B aún no están disponibles: su encode() se cierra de forma segura con la excepción tipada UnsupportedBarcodeFeature. Las palabras de código CC-C incluidas se fijan frente a un golden y se verifican de forma cruzada con un decodificador independiente. No se reclama ninguna GA, conformidad ni certificación de extremo a extremo frente a la norma GS1 Composite, y no se reproduce ningún texto de las normas.

Consulte también

• Módulo Barcode
• Generar códigos de barras 1D y 2D
• Contratos / Barcode