Contracts / บาร์โค้ด

ภาพรวมโดยย่อ

โดเมนบาร์โค้ดกำหนดสัญญาไว้สี่รายการ ได้แก่ ตัวเข้ารหัสหนึ่งมิติ (1D), ตัวเข้ารหัสสองมิติ (2D), ตัวเข้ารหัสทั่วไปที่ค้นพบได้ผ่านรีจิสทรี และตัวแยกวิเคราะห์ข้อมูล GS1 สัญญาเหล่านี้ร่วมกันกำหนดรูปแบบที่บริการบาร์โค้ดต้องปฏิบัติตาม การใช้งานแต่ละ symbology จะลงทะเบียนกับสัญญาเหล่านี้

การติดตั้ง

composer require nextpdf/core:^3

ภาพรวมเชิงแนวคิด

ตัวเข้ารหัสบาร์โค้ดจะแปลงสตริงเพย์โหลดเป็นเมทริกซ์ของโมดูลที่ตัวเขียน Portable Document Format (PDF) นำไปวาด NextPDF แยกสัญญาของตัวเข้ารหัสตามมิติ Barcode1DEncoderInterface จัดการ symbology แบบเชิงเส้น รวมถึง Code 128 และ EAN-13 แล้วคืนค่าเป็นวัตถุค่า BarcodeData ส่วน Barcode2DEncoderInterface จัดการ symbology แบบเมทริกซ์ รวมถึง Quick Response (QR) Code และ Data Matrix โดยคืนค่าเป็นวัตถุค่า Barcode2DData พร้อมแมปตัวเลือกสำหรับการตั้งค่าเฉพาะ symbology เช่น ระดับการแก้ไขข้อผิดพลาด

BarcodeEncoderInterface คือสัญญาผู้ให้บริการแบบทั่วไป ตัวเข้ารหัส 2D ใดๆที่ค้นพบได้ผ่าน BarcodeEncoderRegistry จะนำสัญญานี้ไปใช้งาน สัญญานี้คืนค่าเป็นเมทริกซ์โมโนโครม Barcode2DData หรือเมทริกซ์สี BarcodeColorData อย่างใดอย่างหนึ่ง ดังนั้นตัวเข้ารหัสที่ลงทะเบียนไว้จึงสร้างสัญลักษณ์สีได้โดยไม่ต้องใช้อินเทอร์เฟซแยกต่างหาก ตัวเข้ารหัสควรเป็นแบบไร้สถานะ (stateless) ยกเว้นการกำหนดค่าในเวลาสร้างวัตถุ รีจิสทรีคืนค่าเป็นอินสแตนซ์ที่ใช้ร่วมกันหนึ่งรายการต่อหนึ่งประเภทที่ลงทะเบียนไว้ ดังนั้นสถานะใดๆที่ขึ้นกับการเรียกแต่ละครั้งจะถือเป็นข้อบกพร่อง

Gs1DataParserInterface คือสัญญาสำหรับข้อมูลแบบมีโครงสร้าง ตัวแยกวิเคราะห์นี้แยกวิเคราะห์สตริงองค์ประกอบ GS1 ให้เป็นวัตถุที่มีชนิดข้อมูลกำหนดไว้ จากนั้นเข้ารหัสวัตถุนั้นใหม่สำหรับตัวพา QR Code, Data Matrix หรือ Code 128 แนวทางนี้แยกไวยากรณ์ GS1 ออกจาก symbology ตัวแยกวิเคราะห์ตรวจสอบความถูกต้องของ Application Identifier เพียงครั้งเดียว เมธอดเฉพาะตัวพาจะจัดรูปแบบโครงสร้างที่แยกวิเคราะห์แล้วชุดเดียวกันให้กับแต่ละเป้าหมาย สัญญาทั้งสี่รายการอยู่ในสถานะ stable BarcodeEncoderInterface มีสถานะเสถียรตั้งแต่ 3.0.0 ส่วนรายการอื่นเสถียรตั้งแต่ 1.0.0 เมธอดใหม่จะถูกเพิ่มเข้ามาพร้อมกับการใช้งานเริ่มต้น (default implementation) เท่านั้น

พื้นผิว API

ชนิด	ประเภท	สมาชิกหลัก	ความเสถียร	ตั้งแต่
Barcode1DEncoderInterface	อินเทอร์เฟซ	encode(string): BarcodeData	stable	1.0.0
Barcode2DEncoderInterface	อินเทอร์เฟซ	encode(string, array): Barcode2DData	stable	1.0.0
BarcodeEncoderInterface	อินเทอร์เฟซ	encode(string, array): Barcode2DData|BarcodeColorData	stable	3.0.0
Gs1DataParserInterface	อินเทอร์เฟซ	parse(), encodeForQrCode(), encodeForDataMatrix(), encodeForCode128()	stable	1.0.0

สำหรับสัญญา 2D อาร์เรย์ $options เป็นแบบเฉพาะ symbology เช่น ระดับการแก้ไขข้อผิดพลาดสำหรับ QR Code สัญญาไม่ได้จำกัดคีย์ของอาร์เรย์ดังกล่าว ตัวเข้ารหัสที่ลงทะเบียนไว้แต่ละตัวจะระบุชุดตัวเลือกของตนเองไว้ในเอกสาร

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

examples/10-barcodes.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Barcode\Barcode2DType;
use NextPDF\Barcode\BarcodeType;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Barcode Examples');
$doc->addPage();

$doc->setFont('helvetica', '', 10);
$doc->cell(0, 6, 'Code 128:', newLine: true);
$doc->write1DBarcode('NEXTPDF-2026', BarcodeType::C128, x: 15, y: null, w: 80, h: 20);
$doc->ln(28);

$doc->cell(0, 6, 'QR Code (URL):', newLine: true);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: null, w: 40, h: 40);

$doc->save(__DIR__ . '/output/10-barcodes.pdf');

write1DBarcode() และ write2DBarcode() จะแปลค่าตัวเข้ารหัสผ่านรีจิสทรี โค้ดแอปพลิเคชันของคุณแทบไม่ต้องแตะสัญญาเหล่านี้โดยตรง เพียงระบุชื่อ symbology แล้วรีจิสทรีจะจัดหาตัวเข้ารหัสให้

ตัวอย่างโค้ด — สำหรับการใช้งานจริง

examples/contracts/barcode-production.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\Barcode2DEncoderInterface;
use NextPDF\Contracts\Gs1DataParserInterface;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class Gs1LabelService
{
    public function __construct(
        private Gs1DataParserInterface $parser,
        private Barcode2DEncoderInterface $dataMatrix,
        private LoggerInterface $logger,
    ) {}

    /**
     * Parse a GS1 element string and encode it as a Data Matrix.
     *
     * @param string $elementString A GS1 element string with Application Identifiers.
     */
    public function encodeLabel(string $elementString): \NextPDF\Barcode\Barcode2DData
    {
        try {
            $parsed = $this->parser->parse($elementString);
            $payload = $this->parser->encodeForDataMatrix($parsed);

            return $this->dataMatrix->encode($payload, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('GS1 label encoding failed', [
                'error' => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

บริการนี้พึ่งพาสัญญาของตัวแยกวิเคราะห์และตัวเข้ารหัส บล็อก catch จะบันทึกล็อกและโยน BarcodeException เฉพาะรายการนั้นต่อไปอีกครั้ง โดยไม่ดักจับ \Exception แบบกว้างๆ

กรณีขอบและข้อควรระวัง

• ตัวเข้ารหัสที่ลงทะเบียนไว้จะถูกใช้ร่วมกัน สถานะที่ขึ้นกับการเรียกแต่ละครั้งบนตัวเข้ารหัสจะทำให้การเรนเดอร์แบบขนานเสียหาย ควรรักษาให้ตัวเข้ารหัสไร้สถานะ ยกเว้นการกำหนดค่าในคอนสตรักเตอร์
• BarcodeEncoderInterface::encode() อาจคืนค่าเป็นข้อมูลสีหรือข้อมูลโมโนโครมก็ได้ โค้ดที่ใช้ค่าดังกล่าวต้องจัดการได้ทั้ง Barcode2DData และ BarcodeColorData ไม่ใช่สมมติว่าเป็นโมโนโครมเสมอ
• อาร์เรย์ $options ของ 2D ไม่ได้ถูกสัญญาตรวจสอบความถูกต้อง ตัวเข้ารหัสส่วนใหญ่จะละเลยคีย์ที่ไม่รู้จักโดยไม่แจ้งเตือน ควรตรวจสอบชื่อคีย์กับเอกสารของตัวเข้ารหัสนั้นเอง
• การแยกวิเคราะห์ GS1 เข้มงวดตามไวยากรณ์ สตริงองค์ประกอบที่มี Application Identifier ที่ไม่รู้จักจะทำให้เกิด BarcodeException แทนที่จะสร้างผลการแยกวิเคราะห์บางส่วน ควรตรวจสอบความถูกต้องของอินพุตที่ต้นทาง
• สัญญา 1D และ 2D ใช้แทนกันไม่ได้ การส่งเพย์โหลด QR ให้ตัวเข้ารหัส 1D จะได้สัญลักษณ์ที่ไม่ถูกต้อง รีจิสทรีกำหนดเส้นทางตามประเภท symbology ดังนั้นควรใช้รีจิสทรีแทนการเรียกสัญญาโดยตรง

ประสิทธิภาพ

ต้นทุนการเข้ารหัสจะเพิ่มตามความยาวของเพย์โหลดและขนาดของเมทริกซ์เป้าหมาย ไม่ได้ขึ้นกับสัญญาที่คุณเรียกใช้ เพย์โหลด Code 128 สั้นๆจะเข้ารหัสได้ในระดับไมโครวินาที QR Code ที่หนาแน่นและใช้การแก้ไขข้อผิดพลาดระดับสูงเป็นกรณี 2D ที่หนักที่สุด แต่ยังอยู่ภายใน performance_budget ที่ 1500 ms ของเวลาจริงและ 64 MB ที่จุดสูงสุดสำหรับหน้าตัวอย่างที่มีหลายสัญลักษณ์ได้อย่างสบาย เมทริกซ์จะถูกคำนวณเพียงครั้งเดียวแล้วนำไปวาดเป็นตัวดำเนินการ PDF การทำซ้ำเป็นแบบ bitwise เพราะเพย์โหลดและตัวเลือกชุดเดียวกันจะให้เมทริกซ์โมดูลเดียวกันเสมอ การค้นหาในรีจิสทรีเป็นแบบ O(1) ส่วนที่ทำงานหนักคืออัลกอริทึมของ symbology

หมายเหตุด้านความปลอดภัย

เพย์โหลดของบาร์โค้ดมักได้รับอิทธิพลจากผู้โจมตี เช่น Uniform Resource Locator (URL) ที่สแกนมา หมายเลขซีเรียล หรือรหัสติดตาม สัญญาเหล่านี้เข้ารหัสไบต์ แต่ไม่ได้ตีความไบต์เหล่านั้น QR Code ที่เข้ารหัส URL อันตรายก็ยังเป็น QR Code ที่ถูกต้อง ดังนั้นความน่าเชื่อถือของเพย์โหลดจึงเป็นความรับผิดชอบของผู้ใช้งาน ไม่ใช่ของตัวเข้ารหัส ควรจำกัดความยาวของเพย์โหลดก่อนเข้ารหัสเพื่อจำกัดขนาดของเมทริกซ์และหลีกเลี่ยงการปฏิเสธการให้บริการผ่านสัญลักษณ์ที่ใหญ่เกินไป ตัวแยกวิเคราะห์ GS1 ปฏิเสธ Application Identifier ที่ผิดรูปแบบ ซึ่งช่วยตัดพื้นผิวการแทรกคำสั่งออกไปหนึ่งจุด แต่ไม่ได้ตรวจสอบความถูกต้องเชิงความหมายของเนื้อหาในฟิลด์ที่ถูกต้อง ควรปฏิบัติต่อข้อมูลบาร์โค้ดที่ถอดรหัสแล้วเป็นอินพุตที่ไม่น่าเชื่อถือทุกที่ที่ข้อมูลนั้นกลับเข้าสู่แอปพลิเคชัน

ความสอดคล้องตามมาตรฐาน

ข้อกล่าวอ้าง	มาตรฐาน	การอ้างอิง
สัญลักษณ์ QR Code เป็นไปตามข้อกำหนด symbology เมทริกซ์ของ QR Code	ISO/IEC 18004	symbology ของ QR Code
สัญลักษณ์ Data Matrix เป็นไปตามข้อกำหนด symbology ของ Data Matrix	ISO/IEC 16022	symbology ของ Data Matrix
สัญลักษณ์ Code 128 เป็นไปตามข้อกำหนด symbology เชิงเส้นของ Code 128	ISO/IEC 15417	symbology ของ Code 128
สตริงองค์ประกอบ GS1 ถูกแยกวิเคราะห์ตามไวยากรณ์ Application Identifier ของ GS1	ข้อกำหนดทั่วไปของ GS1	Application Identifier

มาตรฐานเหล่านี้ถูกอ้างอิงด้วยหมายเลขและข้อกำหนด มาตรฐานเหล่านี้ไม่มีอยู่ในคลังข้อมูลการอ้างอิงที่ตรวจสอบได้ จึงไม่มีการบันทึก reference_id เอนจินจะถอดความข้อกำหนดและอ้างอิงแหล่งที่มา ควรศึกษามาตรฐานที่เผยแพร่แล้วเพื่อดูกฎการเข้ารหัสอย่างเป็นทางการ

บริบทเชิงพาณิชย์

Core กำหนดและตรึงสัญญาของตัวเข้ารหัสไว้ และจัดส่ง symbology ทั่วไปมาให้ รุ่น Pro และ Enterprise ลงทะเบียนชุดตัวเข้ารหัสเพิ่มเติมสำหรับ symbology บาร์โค้ดเพิ่มเติมกับ BarcodeEncoderInterface ตัวเดียวกัน ดังนั้นการนำไปใช้งานเชิงพาณิชย์จึงได้รับการรองรับเพิ่มขึ้นโดยไม่ต้องเปลี่ยนแปลง application programming interface (API) Core แปลค่าตัวเข้ารหัสที่ลงทะเบียนไว้ผ่าน BarcodeEncoderRegistry พื้นผิวของสัญญาเหมือนกันในทุกรุ่น

ดูเพิ่มเติม

• Contracts: 41 public interfaces (SPI) — ภาพรวมของ service provider interface (SPI) และลำดับชั้นความเสถียร
• Barcode — การใช้งาน symbology ที่ลงทะเบียนกับสัญญาเหล่านี้
• Contracts / Document — PdfDocumentInterface ที่วาดเมทริกซ์ที่เข้ารหัสแล้ว
• Graphics — เลเยอร์การวาดที่เรนเดอร์โมดูลของบาร์โค้ด
• Exception — BarcodeException ที่ถูกโยนเมื่ออินพุต GS1 ผิดรูปแบบ