Barcode — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Bề mặt mã vạch NextPDF Pro bổ sung các bộ ký hiệu 2D chuyên dụng và chuỗi cung ứng lên trên module mã vạch Core. Nó cung cấp sáu bộ mã hóa 2D được phân giải qua registry (Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), một bộ mã hóa thành phần 2D GS1 Composite (CC-C), bộ mã hóa 1D USPS Intelligent Mail, cùng một bộ phân tích cú pháp GS1 Application Identifier và bộ xác thực chuỗi cung ứng. Việc mã hóa có tính tất định: cùng một payload và các tùy chọn luôn tạo ra một ma trận module giống hệt. Trang này nêu rõ public API, hợp đồng hành vi, các chế độ hỏng, và bằng chứng tính phù hợp theo từng bộ ký hiệu.

Tính khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một license envelope bậc Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực. So sánh các phiên bản và lấy giấy phép.

composer require nextpdf/pro:^3

Mỗi bộ ký hiệu ràng buộc tên năng lực riêng của nó trong license envelope: barcode.microqr, barcode.dotcode, barcode.hanxin, barcode.jabcode, barcode.rmqr, barcode.gs1databar, và barcode.gs1-composite-cc-c. Khi một năng lực chưa được cấp phép, registry không phân giải bộ mã hóa đó. Mã hóa toàn-ký-hiệu GS1 Composite CC-A và CC-B không được hỗ trợ (xem bảng tình trạng hỗ trợ), nên không có khóa barcode.gs1-composite-cc-a hay barcode.gs1-composite-cc-b nào được đăng ký.

Bề mặt public API

Các khóa registry đến từ các giá trị case NextPDF\Barcode\Barcode2DType của Core cộng với khóa literal gs1-composite-cc-c. Đối với các bộ mã hóa được phân giải qua registry, khóa registry là hợp đồng ổn định, chứ không phải FQCN của bộ mã hóa.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc hỏng với	Ghi chú
BarcodeProServiceProvider::register()	BarcodeEncoderRegistry $registry	Ràng buộc cả bảy khóa registry của Pro	void	—	Static; lũy đẳng — lời gọi thứ hai thay thế ràng buộc đầu tiên
MicroQrEncoder::encode()	$data; các tùy chọn ecLevel ('L', 'M', 'Q'; mặc định 'L'), version (1–4 hoặc null), mask (0–3 hoặc null)	Tự động chọn phiên bản M1–M4 nhỏ nhất vừa khớp	Barcode2DData	InvalidArgumentException	'H' không được hỗ trợ ÂM THẦM ép về 'L' (các bên gọi cần chọn EC fail-closed phải tiền-xác-thực); M1 bỏ qua ecLevel
DotCodeEncoder::encode()	$data; các tùy chọn gs1 (bool, mặc định false), columns (int), rows (int), ratio (float, mặc định 1.5)	Tự động định cỡ lưới ở tỉ lệ rộng:cao 1.5	Barcode2DData	InvalidArgumentException	Kích thước lưới có thể bị buộc theo từng trục
HanXinEncoder::encode()	$data; các tùy chọn ecLevel (0–3, mặc định 1), version (1–84, mặc định auto)	Phiên bản nhỏ nhất vừa khớp	Barcode2DData	InvalidArgumentException	Các chế độ văn bản GB 2312 Region 1/2 theo ISO/IEC 20830
JabCodeEncoder::encode()	$data; các tùy chọn colors (4, 8, 16, 32, 64, 128, 256; mặc định 8), eccLevel (0–10, mặc định 3), symbolNumber (1–61, mặc định 1), symbolVersions, symbolPositions, symbolEccLevels	Một ký hiệu 8 màu đơn	BarcodeColorData	InvalidArgumentException, JabCodeEncodingException	Ma trận module đa sắc với bảng màu
RmqrEncoder::encode()	$data; các tùy chọn ecLevel (RmqrConstants::EC_M mặc định, hoặc EC_H), version (ví dụ 'R7x43', mặc định auto)	Phiên bản nhỏ nhất vừa khớp trong 32 phiên bản ISO/IEC 23941	Barcode2DData	InvalidArgumentException	Từ chối các payload vượt dung lượng; không bao giờ cắt bớt
Gs1DataBarEncoder::encode()	$data; các tùy chọn variant (Gs1DataBarVariant, mặc định OMNIDIRECTIONAL), linkage (bool, mặc định false), height (int, mặc định tối thiểu của biến thể; theo từng hàng cho Expanded Stacked), segmentsPerRow (int, mặc định 4; chỉ Expanded Stacked)	Mã hóa đầu vào GTIN (họ §5/§6) hoặc một chuỗi phần tử GS1 AI (họ §7)	Barcode2DData	InvalidArgumentException; InvalidSymbolStructureException	Cả bảy biến thể ISO/IEC 24724 Annex J đều mã hóa được
Gs1DataBarVariant	—	isImplemented() trả về true cho cả bảy case	enum (7 case)	—	minimumHeightX() và defaultHeightX() theo Annex J
ImbEncoder::encode()	string $code (20, 25, 29, hoặc 31 chữ số)	65 thanh bốn trạng thái	BarcodeData	InvalidArgumentException	Giao diện bộ mã hóa 1D; không phải một khóa registry 2D
ImbEncoder::encodeToString()	string $code	Các trạng thái thanh dưới dạng chuỗi T/A/D/F	string	InvalidArgumentException	Để kiểm tra đối chiếu với các vector tham chiếu USPS
Gs1DataParser::parse()	string $data	Tự động phát hiện các URI Digital Link, nếu không thì định dạng (AI)value	Gs1ParsedData	InvalidArgumentException	Hiện thực hợp đồng Gs1DataParserInterface của Core
Gs1DataParser::parseDigitalLink()	string $uri	Phân tích cú pháp một URI GS1 Digital Link	Gs1ParsedData	InvalidArgumentException	—
Gs1DataParser::encodeForCode128() / ::encodeForQrCode() / ::encodeForDataMatrix()	object $parsed	Chuỗi byte carrier với quy ước FNC1 của carrier đó	string	—	Mong đợi một thực thể Gs1ParsedData
Gs1DataParser::validateAI()	string $ai, string $value	Kiểm tra cấu trúc của một giá trị AI	bool	—	—
Gs1Validator::validate()	string $barcodeData, Gs1SupplyChainProfile $profile (mặc định NONE)	Đường tắt static bọc run()	Gs1ValidationResult	—	Các lỗi phân tích cú pháp trở thành finding, không phải exception
Gs1Validator::run()	như validate()	Phân tích cú pháp, check digit, ngày tháng, quy tắc cross-AI, hồ sơ	Gs1ValidationResult	—	Đường instance; constructor chấp nhận một parser được tiêm vào
Gs1SupplyChainProfile	—	NONE bỏ qua các quy tắc hồ sơ	enum (5 case)	—	RETAIL, FOOD, PHARMA, LOGISTICS, NONE; requiredAIs(), recommendedAIs(), primaryIdentifiers()
Gs1ValidationResult	—	Các finding được phân hoạch theo mức nghiêm trọng lúc khởi tạo	readonly class	—	isValid, findings, errors, warnings, infos, parsedData; passes(), fails(), totalFindings()
Gs1ValidationFinding / Gs1FindingSeverity	—	severity, ruleId, message, ai và suggestion tùy chọn	readonly class / enum	—	Các mức nghiêm trọng: Error, Warning, Info
CompositeComponentA::codewordsFor()	string $data	Mã hóa chuỗi-nhị-phân đa dụng §5, chuyển đổi base-928, tự-kiểm round-trip	list<int> (mỗi phần tử 0–927)	InvalidArgumentException	Cấp cho linkFor() hoặc một bộ render carrier CC-A bên ngoài
CompositeComponentA::encode()	bị bỏ qua	Từ chối render toàn-ký-hiệu CC-A	—	UnsupportedBarcodeFeature (luôn luôn)	Fail-closed; xem Các trường hợp biên
CompositeComponentB::encode()	bị bỏ qua	Từ chối mã hóa 2D CC-B	—	UnsupportedBarcodeFeature (luôn luôn)	linkFor() vẫn khả dụng (CCSI 901)
CompositeComponentC::encode()	$data; các tùy chọn được chuyển tiếp tới carrier PDF417; carrierType (mặc định GS1_128)	Carrier PDF417 đầy đủ với CCSI codeword 920 dẫn đầu	Barcode2DData	BarcodeException; CompositeLinkageException	Chỉ carrier GS1_128 là được chấp nhận
CompositeComponent{A,B,C}::linkFor()	string $carrierId, array $codewords, CompositeCarrierType $carrierType	Ghép các codeword thành phần với một carrier 1D	CompositeLinkage	CompositeLinkageException	Thực thi tính chấp-nhận-được và dung lượng của carrier
CompositeVariant / CompositeCarrierType	—	CC_A, CC_B, CC_C; GS1_DATABAR, GS1_128	enum	—	maxCodewords(), ccsi(), allowedCarriers(), usesFullPdf417()

Chữ ký điểm vào

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

Hợp đồng hành vi

Phân giải registry

Registry factory mặc định của Core pre-bind các bộ mã hóa Pro dưới dạng các entry khởi tạo trễ, được cấp phép theo năng lực. BarcodeProServiceProvider::register() là phương án dự phòng được hỗ trợ cho các ứng dụng tạo một registry không có giá trị mặc định, ví dụ các tích hợp framework với container riêng của chúng. Mỗi bộ mã hóa chuyển một payload chuỗi và các tùy chọn theo từng bộ ký hiệu thành một đối tượng dữ liệu mã vạch mà page renderer biến thành các toán tử nội dung PDF.

Phân tích cú pháp và xác thực GS1

Gs1DataParser chấp nhận các chuỗi AI có thể đọc được ((01)09521234543213(17)260131) và các URI GS1 Digital Link. Nó tạo ra các chuỗi byte đã mã hóa cho các carrier GS1-128, QR Code, và Data Matrix, áp dụng quy ước FNC1 và dấu phân tách nhóm của từng carrier. Gs1Validator chạy một pipeline năm bước: phân tích cú pháp, check digit (GTIN, SSCC), logic ngày tháng, quy tắc cross-AI, và các AI bắt buộc theo hồ sơ ngành. Một lỗi phân tích cú pháp tạo ra một kết quả không hợp lệ mang theo các finding; nó không ném exception. Các finding phân hoạch theo mức nghiêm trọng thành error, warning, và info.

Điều phối biến thể GS1 DataBar

Gs1DataBarEncoder::encode() điều phối cả bảy biến thể ISO/IEC 24724:2011 Annex J qua một hợp đồng tùy chọn duy nhất. Omnidirectional, Truncated, Stacked, và Stacked Omnidirectional dùng chung đại số độ-rộng-phần-tử §5 với một ký tự kiểm tra mod-79. Limited dùng đại số ký-tự-ký-hiệu §6 riêng của nó với một ký tự kiểm tra mod-89. Expanded và Expanded Stacked dùng đại số (17,4) của §7: máy trạng thái nén ba chế độ số, chữ-và-số, và ISO/IEC 646 của §7.2.5.5 cộng một ký tự kiểm tra mod-211 (§7.2.6). Họ §5/§6 nhận một GTIN-14 14 chữ số với check digit mod-10 hoặc một mã định danh mặt hàng 13 chữ số. Họ §7 nhận một chuỗi phần tử GS1 AI thô (chữ số, chữ cái, tập con dấu câu ISO/IEC 646, FNC1 dưới dạng byte 0x1D). Tùy chọn linkage đặt cờ liên kết thành-phần-2D để dùng làm thành phần tuyến tính của một ký hiệu GS1 Composite.

Các thành phần GS1 Composite

CC-C tạo ra một thành phần mở rộng 2D hoàn chỉnh trên carrier PDF417 đầy đủ, chèn CCSI codeword 920 bắt buộc làm data codeword dẫn đầu (ISO/IEC 24723:2010 §5.4). CC-A tạo ra các data codeword base-928 phù hợp qua codewordsFor(), với một tự-kiểm round-trip mã-hóa-giải-mã fail-closed, nhưng từ chối render toàn-ký-hiệu. CC-B từ chối hoàn toàn việc mã hóa 2D. linkFor() ghép các codeword thành phần với một carrier 1D dưới dạng một giá trị CompositeLinkage, thực thi tính chấp-nhận-được và dung lượng của carrier.

Các trường hợp biên & chế độ hỏng

• Mọi bộ mã hóa từ chối một payload rỗng với InvalidArgumentException.
• Micro QR: yêu cầu mức sửa lỗi H không được hỗ trợ ÂM THẦM ép về L thay vì báo lỗi (tiền-xác-thực các tùy chọn nếu bạn cần chọn EC fail-closed), vì ISO/IEC 18004 chỉ định nghĩa L, M, và Q cho các ký hiệu Micro QR.
• rMQR: mức sửa lỗi phải là M hoặc H; một payload vượt dung lượng của 32 phiên bản bị từ chối, không bao giờ bị cắt bớt.
• JabCode: một số lượng màu ngoài tập lũy-thừa-của-hai được hỗ trợ, một mức ECC ngoài 0–10, hoặc một số lượng ký hiệu ngoài 1–61 bị từ chối; các lỗi mã hóa hạ nguồn ném JabCodeEncodingException.
• GS1 DataBar: họ §5/§6 xác thực check digit mod-10 của GTIN, và Limited giới hạn chữ số chỉ báo ở 0 hoặc 1. Họ §7 từ chối các ký tự không mã hóa được và các dấu phân tách FNC1 ở cuối hoặc bị nhân đôi. Expanded Stacked từ chối một số lượng ký-tự-ký-hiệu lẻ trên mỗi hàng và các chiều cao theo hàng dưới mức tối thiểu 34X. Các tự-kiểm cấu trúc nội bộ hỏng với InvalidSymbolStructureException thay vì phát ra một ký hiệu dị dạng.
• GS1 Composite: encode() của CC-A và CC-B luôn ném UnsupportedBarcodeFeature (fail closed). CC-C ném BarcodeException khi dữ liệu rỗng hoặc tràn dung lượng PDF417 (nhiều hơn 925 codeword), và CompositeLinkageException cho một carrier không được chấp nhận.
• Xác thực GS1 gắn cờ cấu trúc AI dị dạng và các check digit sai trước khi mã hóa; một chuỗi chuỗi cung ứng không hợp lệ không bao giờ tạo ra một ký hiệu phù hợp có thể quét được.
• IMB chỉ chấp nhận các đầu vào 20, 25, 29, hoặc 31 chữ số.
• Mã hóa mã vạch không thực hiện mật mã nào. Không có hành vi riêng cho chế độ FIPS; các bộ mã hóa chạy giống hệt nhau bất kể hồ sơ FIPS.

Tính phù hợp

NextPDF hiện thực các bộ ký hiệu này theo các tiêu chuẩn đã xuất bản được trích dẫn dưới đây và ghim các reference trace trong bộ test của nó. Các phát biểu trên trang này là các khẳng định năng lực: hỗ trợ không phải là tính phù hợp, và tính phù hợp không phải là chứng nhận. NextPDF không giữ chứng nhận bộ ký hiệu nào. Các neo điều khoản được diễn giải lại từ mã nguồn sản phẩm và các fixture tính phù hợp của nó; corpus của compliance-engine không bao phủ các tiêu chuẩn bộ ký hiệu mã vạch, nên các neo dưới đây được đặt-nền-trên-sản-phẩm mà không có định danh tham chiếu.

Bề mặt	Tiêu chuẩn	Neo điều khoản (diễn giải lại)
Đại số độ rộng phần tử GS1 DataBar	ISO/IEC 24724:2011	§5.2 symbol-character structure; Annex F.1 worked example (Omnidirectional); Annex F.2 (Limited); Annex F.3 (Expanded)
Các bố cục xếp chồng GS1 DataBar	ISO/IEC 24724:2011	§5.4 Stacked; §5.5 Stacked Omnidirectional; §7.2.8 Expanded Stacked row partition and separators
Mã hóa GS1 DataBar Expanded	ISO/IEC 24724:2011	§7.2.5.5 three-mode compaction state machine; §7.2.6 mod-211 check character
Liên kết GS1 Composite và CC-C	ISO/IEC 24723:2010	§5.4 CCSI codeword semantics; §5.1 carrier admissibility
Các codeword GS1 Composite CC-A	ISO/IEC 24723:2010	§5 general-purpose binary-string encodation with base-928 conversion
Cấu trúc ký hiệu rMQR	ISO/IEC 23941:2022	§6.3.2 Table 1 version dimensions; §7.8.2 fixed mask; Annex C / Annex I format-information reference
Micro QR	ISO/IEC 18004	Micro QR M1–M4 capacity and format information
Han Xin Code	ISO/IEC 20830:2021	Symbol structure; finder and alignment patterns; GB 2312 Region 1/2 modes; Reed–Solomon ECC; masking
JabCode	ISO/IEC 23634	Symbol, colour, and ECC structure
Bộ ký hiệu bưu chính	USPS-B-3200	Intelligent Mail Barcode field structure

Tình trạng hỗ trợ theo từng bộ ký hiệu

Một biến thể là Verified khi một fixture dưới pro/tests/** thực thi nó, tốt nhất là một reference trace được ghim vào một ví dụ đã giải đã xuất bản. Một biến thể đã đi kèm mà không có fixture chuyên dụng vẫn ở mức Claimed. Một biến thể không có bộ mã hóa là Not supported.

Bộ ký hiệu / biến thể	Tình trạng	Bằng chứng (đường dẫn test)	Ghi chú
Micro QR (M1–M4)	Verified	pro/tests/Unit/Barcode/MicroQrEncoderTest.php	Mức unit; một fixture reference-trace ví-dụ-đã-giải là một backfill được theo dõi
DotCode	Verified	pro/tests/Unit/Barcode/DotCodeEncoderTest.php; DotCodeGfArithmeticTest.php	Số học trường Galois được bao phủ; không có round trip với decoder của nhà cung cấp
Han Xin Code	Verified	pro/tests/Unit/Barcode/HanXinEncoderTest.php; HanXinRsEncodingTest.php	Đường mã hóa Reed–Solomon được thực thi tường minh
JabCode (1–61 symbols, 4–256 colors, ECC 0–10)	Verified	pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php (+ 11 bộ suite thành phần trong cùng thư mục)	Chuỗi đa-ký-hiệu (cascade) và dải ECC được thực thi; không có round trip với decoder của nhà cung cấp
USPS Intelligent Mail Barcode	Verified	pro/tests/Unit/Barcode/ImbEncoderTest.php; ImbRoutingCodeTest.php	Xác thực routing-code và độ dài 20/25/29/31 chữ số được thực thi
rMQR — tất cả 32 phiên bản ISO/IEC 23941	Verified	pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php; RmqrAnnexCFormatInfoTest.php; pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php	Các cặp phiên bản và EC được kiểm tra đối chiếu với ISO/IEC 23941 Table 1; các giá trị tham chiếu thông-tin-định-dạng Annex C / Annex I
GS1 DataBar — Omnidirectional / Truncated	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php	Byte-equal với ví dụ đã giải Annex F.1; Truncated dùng chung mã hóa ở chiều cao giảm
GS1 DataBar — Stacked / Stacked Omnidirectional	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php	Row split dẫn xuất từ trace Annex F.1; kiến tạo dấu phân tách theo §5.4 và §5.5
GS1 DataBar — Limited	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php; pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php	Byte-equal với ví dụ đã giải Annex F.2 (mặt hàng 00098765432105)
GS1 DataBar — Expanded	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php; pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php	Byte-equal với ví dụ đã giải Annex F.3 ((10)12A); round trip decoder độc lập đối chiếu zxing-cpp và ZBar
GS1 DataBar — Expanded Stacked	Verified	pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php (các case stacked); round trip tích hợp ở trên	Cùng pipeline dữ liệu như Expanded một hàng; phân hoạch hàng §7.2.8 và các dấu phân tách được khẳng định
GS1 Composite — CC-C (PDF417 carrier)	Verified	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php; CompositeRoundtripTest.php; CompositeLinkageTest.php	CCSI codeword 920 và tương tác cờ liên kết được bao phủ
GS1 Composite — CC-A	Partial	pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php; pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php	Sinh codeword đã Verified (base-928, tự-kiểm round-trip); render toàn-ký-hiệu không được hỗ trợ — encode() fail closed
GS1 Composite — CC-B	Not supported	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php (khẳng định từ chối fail-closed)	Không có mã hóa 2D; trình trợ giúp liên kết (CCSI 901) vẫn khả dụng
GS1 AI parser	Verified	pro/tests/Unit/Barcode/Gs1DataParserTest.php; Gs1DataParserFnc1Test.php	Cả hai định dạng đầu vào và cả ba đầu ra chuỗi-byte carrier được thực thi
GS1 supply-chain validator	Verified	pro/tests/Unit/Barcode/Gs1ValidatorTest.php; Gs1ValidatorCrossAiTest.php; pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php	Các check digit, tổ hợp bắt buộc cross-AI, và logic ngày tháng được thực thi

Ghi chú phát triển

• Các neo bằng chứng trên trang này là các đường dẫn test dưới pro/tests/**; kho không cung cấp thư mục examples/ cho module này.
• Bảy tên năng lực được liệt kê dưới Tính khả dụng & cấp phép là các khóa mà service provider ràng buộc. Bộ mã hóa IMB được khởi tạo trực tiếp và không mang khóa registry nào.
• CC-A chỉ phát ra phương pháp mã hóa đa dụng; các phương pháp nén dành riêng cho ứng dụng là một khoảng dư mật độ đã được ghi nhận, không phải một khoảng trống về tính đúng đắn.

Ranh giới công bố

Trang này chỉ ghi lại hành vi có thể quan sát từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.

Xem thêm

• Tổng quan năng lực barcode (NextPDF Pro)
• Tài liệu tham chiếu chuyên sâu Chart
• Module barcode Core