GS1 Composite 바코드 생성하기(CC-C 캐리어)

한눈에 보기

옵트인 프리뷰 능력 — 기본적으로 꺼짐. GS1 Composite 지원은 실험적인 옵트인 기능입니다. 출하된 단일 복합은 CC-C(완전한 PDF417 캐리어)입니다. Core는 barcode.gs1-composite-cc-c 능력을 등록하고 Premium(nextpdf/pro) 패키지가 그 뒤에서 인코더를 게이트합니다. Core만으로는 능력이 등록되지만 그 상태가 Unavailable이므로, 아무것도 발행되지 않습니다. CC-A와 CC-B는 아직 사용할 수 없습니다. 둘 중 하나를 인코딩하려는 요청은 타입 지정 예외 (UnsupportedBarcodeFeature)와 함께 fail-closed 처리됩니다. 이는 문서화된 범위 경계이지 결함이 아닙니다.

GS1 Composite 심볼은 선형 구성 요소(주 항목 식별자)를 2D 복합 구성 요소(배치나 유효 기간 같은 확장 데이터)와 짝짓습니다. 이 레시피는 복합 능력이 어떻게 등록되고 해석되는지, Core가 무엇을 제공하는지, Premium이 무엇을 추가하는지, 그리고 지원이 정확히 어디에서 멈추는지를 보여줍니다.

설치

composer require nextpdf/core:^3

CC-C 복합 인코더는 Premium 패키지가 필요합니다.

composer require nextpdf/pro

개념 개요

NextPDF는 Barcode 모듈이 어떤 인코더든 해석하는 것과 같은 방식으로, 능력 레지스트리를 통해 심볼로지를 해석합니다. 거기에 하나의 GS1 Composite 능력이 등록되어 있습니다.

• **barcode.gs1-composite-cc-c**는 Core의 CapabilityRegistry에 Pro 제품 티어 아래에 등록되어 있습니다. 이것은 CC-C 복합 구성 요소를 위한 완전한 PDF417 캐리어(ISO/IEC 15438)입니다. Pro 인코더는 페이로드를 정규 코어 PDF417 인코더를 통해 라우팅합니다. 이 능력은 항상 등록되지만 Premium이 설치되어 있을 때만 Available 합니다 — Core만으로는 그 상태가 Unavailable이므로, 등록되어 있되 비활성입니다(옵트인, 기본적으로 꺼짐).

CC-A나 CC-B 능력은 등록되어 있지 않습니다. 적합한 CC-A/CC-B 2D 구성 요소는 ISO/IEC 24723 Clause 5 base-928 고수준 인코데이션과 구성 요소별 캐리어가 필요하며, 이번 릴리스는 그 경로를 구현하지 않으므로, CC-A/CC-B 능력을 광고하는 것은 디코딩 가능한 심볼을 발행할 수 없는 인코더를 이름 짓는 셈이 됩니다.

Fail-closed 경계 — 아직 사용할 수 없는 것

CC-A와 CC-B는 의도적으로 사용 가능한 심볼로지로 출하되지 않았습니다.

• CC-A — 저수준 base-928 기수 프리미티브(Base928Converter, 코드워드만)와 Clause-5 이진 문자열 빌더가 내부적으로 존재하지만, 완전한 ISO/IEC 24723 Clause 5 CC-A 고수준 인코데이션과 CC-A 전용 캐리어는 구현되어 있지 않으므로, 사용 가능한 CC-A 심볼은 생성되지 않습니다. CompositeComponentA::encode()는 항상 타입 지정 UnsupportedBarcodeFeature 예외를 던집니다.
• CC-B — 중간 용량 복합 구성 요소 역시 구현되어 있지 않습니다. CompositeComponentB::encode()는 항상 UnsupportedBarcodeFeature를 던집니다.

이것들은 fail-closed 처리됩니다. 둘 중 하나를 인코딩하려는 요청은 부분적이거나 잘못된 심볼을 발행하는 대신 타입 지정 예외를 발생시킵니다. 이는 결함이 아니라 의도적인 범위 선입니다.

출하된 CC-C 경로는 코드워드 골든 규율을 따릅니다. 생성된 코드워드는 골든에 대해 고정되고 독립적인 디코더로 교차 점검되므로, CC-C 코드워드 스트림은 단지 생성된 것이 아니라 검증된 것입니다. GS1 Composite 표준에 대한 종단 간 인증은 주장되지 않습니다.

API 표면

GS1 Composite 심볼은 새로운 최상위 파사드 메서드가 아니라 능력 레지스트리를 통해 해석됩니다.

• NextPDF\Support\CapabilityRegistry — 현재 에디션에서 barcode.gs1-composite-cc-c가 Available인지 보고하는 조회입니다. 가용성 결정에는 get('barcode.gs1-composite-cc-c')->status를 사용하세요. has()는 능력이 등록되어 있다는 것만 보고하므로(Core 전용 설치에서도 true), 가용성 게이트가 아닙니다.
• CC-C 복합 인코더는 nextpdf/pro가 공급하며, Contracts / Barcode 페이지가 문서화하는 것과 동일한 인코더 계약 뒤에 등록됩니다.
• 호출할 CC-A나 CC-B 인코더는 없습니다. CC-A/CC-B 구성 요소 클래스는 encode()에서 fail-closed 처리됩니다.

생성된 인코더 표를 보려면 composer docs:generate-api-php -- --module=Barcode를 실행하세요.

코드 샘플 — 빠른 시작

CC-C 캐리어 능력에 의존하기 전에 그것이 사용 가능한지 확인하세요. Core만으로는 등록되어 있되 Unavailable이며, Premium이 설치되어 있으면 Available입니다. has()가 아니라 상태로 게이트하세요 — has()는 능력이 항상 등록되어 있기 때문에 Core 전용 설치에서도 true입니다.

<?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입니다. has()가 아니라 get(...)->status로 게이트하세요 — has()는 항목이 항상 등록되어 있기 때문에 Core 전용에서도 true입니다.
• 사용 가능한 CC-A 인코더는 없습니다. 저수준 base-928 기수 프리미티브가 내부적으로 존재하지만, 완전한 ISO/IEC 24723 Clause 5 CC-A 고수준 인코데이션과 CC-A 전용 캐리어는 구현되어 있지 않으므로, CC-A 심볼은 생성되지 않습니다.
• CC-A와 CC-B는 fail-closed 처리됩니다. 이들의 encode()는 부분 심볼을 발행하는 대신 항상 타입 지정 UnsupportedBarcodeFeature 예외를 던집니다. 이는 의도적으로 문서화된 범위 경계입니다.
• GS1 애플리케이션 식별자는 여전히 적용됩니다. 선형 구성 요소는 1D 및 2D 바코드 생성하기에서처럼 FNC1 접두사와 함께 GS1 구조화 데이터를 운반합니다.
• 페이로드를 제한하세요. 더 큰 복합 페이로드는 더 조밀한 심볼을 산출합니다. 인코딩 전에 페이로드 길이를 제한하세요.

성능

코드워드 생성은 페이로드 길이에 선형이며, 캐리어 발행은 매트릭스 면적에 선형입니다. 래스터화 단계가 없으므로 — 각 모듈은 경로 연산자입니다 — 심볼 크기와 무관하게 메모리가 평탄하게 유지됩니다. 이 레시피는 1500 ms / 64 MB 예산 안에 머무릅니다.

보안 참고

복합 심볼은 여러분이 전달하는 어떤 페이로드든 운반합니다. 소비하는 쪽에서는 그 값을 신뢰 없는 것으로 취급하세요. 인코더는 바이트를 인코딩하며 그것을 인증하지 않습니다. 심볼 크기와 작업을 예산 안에 유지하려면 인코딩 전에 페이로드 길이를 제한하세요.

적합성

진술	사양	절
출하된 CC-C 복합 구성 요소는 PDF417 캐리어를 사용합니다.	ISO/IEC 15438 (PDF417)	§5
CC-A의 base-928 고수준 인코데이션은 이번 릴리스가 구현하지 않는 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 예외와 함께 fail-closed 처리됩니다. 출하된 CC-C 코드워드는 골든에 대해 고정되고 독립적인 디코더로 교차 점검됩니다. GS1 Composite 표준에 대한 GA, 적합성, 또는 종단 간 인증은 주장되지 않으며, 표준 텍스트는 재현되지 않습니다.

함께 보기

• Barcode 모듈
• 1D 및 2D 바코드 생성하기
• Contracts / Barcode