Pro 에디션

Barcode — 심층 참조

한눈에 보기

NextPDF Pro 바코드 표면은 Core 바코드 모듈 위에 특수 2D 및 공급망 심볼로지를 더합니다. 여기에는 레지스트리로 해석되는 여섯 개의 2D 인코더(Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), 하나의 GS1 Composite 2D 구성 요소 인코더(CC-C), USPS Intelligent Mail 1D 인코더, 그리고 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, 기본 auto)	가장 작은 적합 버전	`Barcode2DData`	`InvalidArgumentException`	ISO/IEC 20830에 따른 GB 2312 Region 1/2 텍스트 모드
`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'`, 기본 auto)	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 Annex J 변형 모두 인코딩
`Gs1DataBarVariant`	—	`isImplemented()`가 일곱 케이스 모두에 대해 true 반환	enum (7 케이스)	—	Annex J에 따른 `minimumHeightX()`와 `defaultHeightX()`
`ImbEncoder::encode()`	`string $code`(20, 25, 29, 또는 31자리)	65개의 4상태 바	`BarcodeData`	`InvalidArgumentException`	1D 인코더 인터페이스; 2D 레지스트리 키가 아님
`ImbEncoder::encodeToString()`	`string $code`	바 상태를 T/A/D/F 문자열로	`string`	`InvalidArgumentException`	USPS 참조 벡터에 대한 검사용
`Gs1DataParser::parse()`	`string $data`	Digital Link URI를 자동 감지, 그렇지 않으면 `(AI)value` 형식	`Gs1ParsedData`	`InvalidArgumentException`	Core `Gs1DataParserInterface` 계약을 구현
`Gs1DataParser::parseDigitalLink()`	`string $uri`	GS1 Digital Link URI를 파싱	`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`은 프로필 규칙을 건너뜀	enum (5 케이스)	—	`RETAIL`, `FOOD`, `PHARMA`, `LOGISTICS`, `NONE`; `requiredAIs()`, `recommendedAIs()`, `primaryIdentifiers()`
`Gs1ValidationResult`	—	생성 시 발견을 심각도로 분할	readonly class	—	`isValid`, `findings`, `errors`, `warnings`, `infos`, `parsedData`; `passes()`, `fails()`, `totalFindings()`
`Gs1ValidationFinding` / `Gs1FindingSeverity`	—	`severity`, `ruleId`, `message`, 선택적 `ai`와 `suggestion`	readonly class / enum	—	심각도: `Error`, `Warning`, `Info`
`CompositeComponentA::codewordsFor()`	`string $data`	§5 범용 이진 문자열 인코데이션, base-928 변환, 라운드 트립 자체 검사	`list<int>`(각 0–927)	`InvalidArgumentException`	`linkFor()` 또는 외부 CC-A 캐리어 렌더러에 공급
`CompositeComponentA::encode()`	무시됨	CC-A 전체 심볼 렌더링 거부	—	`UnsupportedBarcodeFeature`(항상)	실패-차단; 엣지 케이스 참조
`CompositeComponentB::encode()`	무시됨	CC-B 2D 인코딩 거부	—	`UnsupportedBarcodeFeature`(항상)	`linkFor()`는 계속 사용 가능(CCSI 901)
`CompositeComponentC::encode()`	`$data`; 옵션은 PDF417 캐리어로 전달; `carrierType`(기본 `GS1_128`)	CCSI 코드워드 920을 선두로 하는 전체 PDF417 캐리어	`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`	enums	—	`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)과 GS1 Digital Link URI를 받습니다. 각 캐리어의 FNC1과 그룹 구분자 관례를 적용하여 GS1-128, QR Code, Data Matrix 캐리어용 인코딩된 바이트 시퀀스를 생성합니다. Gs1Validator는 다섯 단계 파이프라인을 실행합니다: 파싱, 체크 디지트(GTIN, SSCC), 날짜 로직, 교차 AI 규칙, 산업 프로필 필수 AI. 파싱 실패는 발견을 담은 유효하지 않은 결과를 산출하며 예외를 던지지 않습니다. 발견은 심각도에 따라 오류, 경고, 정보로 분할됩니다.

GS1 DataBar 변형 디스패치

Gs1DataBarEncoder::encode()는 일곱 개의 ISO/IEC 24724:2011 Annex J 변형 모두를 하나의 옵션 계약을 통해 디스패치합니다. Omnidirectional, Truncated, Stacked, Stacked Omnidirectional은 mod-79 검사 문자를 갖는 §5 요소 너비 대수를 공유합니다. Limited는 mod-89 검사 문자를 갖는 자체 §6 심볼 문자 대수를 사용합니다. Expanded와 Expanded Stacked는 §7 (17,4) 대수를 사용합니다: §7.2.5.5 3모드 숫자, 영숫자, ISO/IEC 646 압축 상태 기계와 mod-211 검사 문자(§7.2.6). §5/§6 패밀리는 mod-10 체크 디지트를 갖는 14자리 GTIN-14 또는 13자리 품목 식별을 받습니다. §7 패밀리는 원시 GS1 AI 요소 문자열(숫자, 문자, ISO/IEC 646 구두점 부분집합, 바이트 0x1D인 FNC1)을 받습니다. linkage 옵션은 GS1 Composite 심볼의 선형 구성 요소로 사용하기 위한 2D 구성 요소 연결 플래그를 설정합니다.

GS1 Composite 구성 요소

CC-C는 필수 CCSI 코드워드 920을 선두 데이터 코드워드로 주입하여 전체 PDF417 캐리어에 걸친 완전한 2D 확장 구성 요소를 생성합니다(ISO/IEC 24723:2010 §5.4). CC-A는 실패-차단 인코딩-디코딩 라운드 트립 자체 검사와 함께 codewordsFor()를 통해 적합한 base-928 데이터 코드워드를 생성하지만, 전체 심볼 렌더링은 거부합니다. CC-B는 2D 인코딩을 전면 거부합니다. linkFor()는 구성 요소 코드워드를 CompositeLinkage 값으로 1D 캐리어와 짝지으며, 캐리어 허용성과 용량을 강제합니다.

엣지 케이스 및 실패 모드

모든 인코더는 빈 페이로드를 InvalidArgumentException으로 거부합니다.
Micro QR: 지원되지 않는 H 오류 정정 수준을 요청하면 실패하는 대신 조용히 L로 강제됩니다(실패-차단 EC 선택이 필요하면 옵션을 사전 검증하세요). ISO/IEC 18004이 Micro QR 심볼에 대해 L, M, Q만 정의하기 때문입니다.
rMQR: 오류 정정 수준은 M 또는 H여야 합니다. 32개 버전의 용량을 초과하는 페이로드는 거부되며 절대 잘리지 않습니다.
JabCode: 지원되는 2의 거듭제곱 집합을 벗어난 색상 수, 0–10을 벗어난 ECC 수준, 또는 1–61을 벗어난 심볼 수는 거부됩니다. 다운스트림 인코딩 실패는 JabCodeEncodingException을 일으킵니다.
GS1 DataBar: §5/§6 패밀리는 GTIN mod-10 체크 디지트를 검증하며, Limited는 지시 숫자를 0 또는 1로 제한합니다. §7 패밀리는 인코딩할 수 없는 문자와 후행 또는 이중 FNC1 구분자를 거부합니다. Expanded Stacked는 행당 홀수 심볼 문자 수와 34X 최소값 미만의 행당 높이를 거부합니다. 내부 구조 자체 검사는 잘못된 심볼을 방출하는 대신 InvalidSymbolStructureException으로 실패합니다.
GS1 Composite: CC-A와 CC-B의 encode()는 항상 UnsupportedBarcodeFeature를 던집니다(실패-차단). CC-C는 빈 데이터 또는 PDF417 용량 초과(925 코드워드 초과)에 대해 BarcodeException을, 허용되지 않는 캐리어에 대해 CompositeLinkageException을 던집니다.
GS1 검증은 인코딩 전에 잘못된 AI 구조와 잘못된 체크 디지트를 표시합니다. 유효하지 않은 공급망 문자열은 스캔 가능한 적합 심볼을 결코 생성하지 않습니다.
IMB는 20, 25, 29, 또는 31자리 입력만 받습니다.
바코드 인코딩은 암호화를 수행하지 않습니다. FIPS 모드 관련 동작은 없습니다. 인코더는 FIPS 프로필과 무관하게 동일하게 실행됩니다.

적합성

NextPDF는 아래에 인용된 발행 표준에 대조하여 이러한 심볼로지를 구현하고 테스트 스위트에 참조 트레이스를 고정합니다. 이 페이지의 진술은 기능 주장입니다: 지원은 적합성이 아니며, 적합성은 인증이 아닙니다. NextPDF는 어떤 심볼로지 인증도 보유하지 않습니다. 조항 앵커는 제품 소스와 그 적합성 픽스처에서 의역한 것입니다. 컴플라이언스 엔진 코퍼스는 바코드 심볼로지 표준을 다루지 않으므로, 아래 앵커는 참조 식별자 없이 제품에 근거합니다.

표면	표준	조항 앵커 (의역)
GS1 DataBar 요소 너비 대수	ISO/IEC 24724:2011	§5.2 심볼 문자 구조; Annex F.1 워크드 예제(Omnidirectional); Annex F.2(Limited); Annex F.3(Expanded)
GS1 DataBar stacked 레이아웃	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 3모드 압축 상태 기계; §7.2.6 mod-211 검사 문자
GS1 Composite 연결 및 CC-C	ISO/IEC 24723:2010	§5.4 CCSI 코드워드 시맨틱; §5.1 캐리어 허용성
GS1 Composite CC-A 코드워드	ISO/IEC 24723:2010	§5 base-928 변환을 갖춘 범용 이진 문자열 인코데이션
rMQR 심볼 구조	ISO/IEC 23941:2022	§6.3.2 Table 1 버전 치수; §7.8.2 고정 마스크; Annex C / Annex I 포맷 정보 참조
Micro QR	ISO/IEC 18004	Micro QR M1–M4 용량 및 포맷 정보
Han Xin Code	ISO/IEC 20830:2021	심볼 구조; finder 및 alignment 패턴; GB 2312 Region 1/2 모드; Reed–Solomon ECC; 마스킹
JabCode	ISO/IEC 23634	심볼, 색상, ECC 구조
Postal 심볼로지	USPS-B-3200	Intelligent Mail Barcode 필드 구조

심볼로지별 지원 상태

변형은 pro/tests/** 아래의 픽스처가 이를 실행할 때 — 가급적 발행된 워크드 예제에 고정된 참조 트레이스일 때 — Verified입니다. 전용 픽스처가 없는 제공된 변형은 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`	Reed–Solomon 인코딩 경로가 명시적으로 실행됨
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 쌍을 ISO/IEC 23941 Table 1에 대조 검사; Annex C / Annex I 포맷 정보 참조 값
GS1 DataBar — Omnidirectional / Truncated	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php`	Annex F.1 워크드 예제와 바이트 동일; Truncated는 감소된 높이에서 인코딩을 공유
GS1 DataBar — Stacked / Stacked Omnidirectional	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php`	Annex F.1 트레이스에서 파생된 행 분할; §5.4와 §5.5에 따른 구분자 구성
GS1 DataBar — Limited	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php`; `pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php`	Annex F.2 워크드 예제(item 00098765432105)와 바이트 동일
GS1 DataBar — Expanded	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php`; `pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php`	Annex F.3 워크드 예제(`(10)12A`)와 바이트 동일; zxing-cpp 및 ZBar에 대한 독립 디코더 라운드 트립
GS1 DataBar — Expanded Stacked	Verified	`pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php`(stacked 케이스); 위의 통합 라운드 트립	단일 행 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(base-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 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일 이름, 티켓 접두사는 범위 밖입니다.