Barcode: ตัวเข้ารหัสซิมโบโลยี 1D และ 2D

ภาพรวมโดยสรุป

โมดูล Barcode จัดเตรียมเลเยอร์ การนำซิมโบโลยีไปใช้งานจริง โดยเข้ารหัสซิมโบโลยีแบบเส้น (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, รหัสไปรษณีย์) และซิมโบโลยีแบบเมทริกซ์ (QR Code, Data Matrix, PDF417) โมดูลนี้คำนวณการแก้ไขข้อผิดพลาดและลงทะเบียนตัวเข้ารหัสแต่ละตัวไว้ภายใต้สัญญาบาร์โค้ด เพื่อให้ตัวเขียนเอกสารวาดผลลัพธ์ออกมาได้ ส่วน คำนิยาม ของสัญญาจะอยู่ในหน้าแยกต่างหาก ดูหมายเหตุด้านล่าง

หนึ่งหน้าหลักต่อหนึ่งประเด็น อินเทอร์เฟซที่ตัวเข้ารหัสรองรับ (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) มีการบันทึกไว้ที่ Contracts / Barcode หน้านี้บันทึกข้อมูล ตัวเข้ารหัสรูปธรรมที่นำสัญญาเหล่านั้นไปใช้งานจริง หน้าทั้งสอง เสริมซึ่งกันและกัน ไม่ใช่ของซ้ำกัน อ่านหน้าสัญญาเพื่อดูอินเทอร์เฟซของผู้ให้บริการ (SPI) อ่านหน้านี้เพื่อดูซิมโบโลยีต่างๆ

การติดตั้ง

composer require nextpdf/core:^3

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

ตัวเข้ารหัสบาร์โค้ดจะแปลงสตริงข้อมูลเพย์โหลดให้เป็นเมทริกซ์โมดูลสองมิติ (2D) หรือลำดับแท่งหนึ่งมิติ (1D) ซึ่งตัวเขียนจะวาดออกมาเป็นกราฟิก Portable Document Format (PDF) โมดูลนี้จัดเตรียมตัวเข้ารหัสรูปธรรม

Barcode1D คือเอนจินแบบเส้น BarcodeType ระบุรายการซิมโบโลยีแบบเส้นที่รองรับ ได้แก่ Code 39 (ทั้งแบบมีและไม่มีเช็คซัม), Code 93, ตระกูล Code 128, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved และ Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB) และ MSI ส่วน generate() จะคืนค่าออบเจ็กต์ค่า BarcodeData ที่อธิบายรูปแบบของแท่ง

ตัวเข้ารหัส 2D คือ QrEncoder, DataMatrixEncoder และ Pdf417Encoder ซึ่งนำ BarcodeEncoderInterface ไปใช้งานจริงและคืนค่าเมทริกซ์ Barcode2DData ส่วน Barcode2DType ระบุรายการซิมโบโลยีแบบเมทริกซ์ที่เอนจินรู้จัก รวมถึง QR Code, Data Matrix และ PDF417 ซิมโบโลยีเพิ่มเติม เช่น Micro QR, rMQR, GS1 DataBar และ Han Xin ระบุไว้สำหรับการกำหนดเส้นทางในรีจิสทรี ชุดตัวเข้ารหัสที่รองรับซิมโบโลยีแต่ละแบบขึ้นอยู่กับรุ่น (edition) การแก้ไขข้อผิดพลาดของเมทริกซ์คำนวณบน Galois field GaloisField และ GaloisFieldPrime จัดเตรียมเลขคณิตแบบ Reed-Solomon ที่ใช้ร่วมกันโดยตัวเข้ารหัส QR, Data Matrix และ PDF417

BarcodeEncoderRegistry คือตัวค้นหา ตัวค้นหานี้นำ PHP Standards Recommendation 11 (PSR-11) ContainerInterface ไปใช้งานจริง จัดเตรียมการลงทะเบียนค่าเริ่มต้นผ่าน createDefault() และแปลงซิมโบโลยีให้เป็นตัวเข้ารหัสของซิมโบโลยีนั้นด้วย resolve() โค้ดของแอปพลิเคชันแทบไม่จำเป็นต้องเข้าถึงตัวเข้ารหัสโดยตรง ฟาซาดระดับสูง Document::write1DBarcode() / write2DBarcode() ระบุชื่อซิมโบโลยี แล้วรีจิสทรีจะจัดหาตัวเข้ารหัสให้ เอนจิน 1D คือ @since 1.0.0 ตัวเข้ารหัส 2D คือ @since 1.3.0 รีจิสทรีคือ @since 3.0.0

พื้นผิว API

คลาส	สมาชิกสำคัญ	บทบาท
Barcode1D	generate(string $code, BarcodeType $type): BarcodeData	ตัวเข้ารหัสซิมโบโลยีแบบเส้น (@since 1.0.0)
QrEncoder	encode(string $data, array $options = []): Barcode2DData	ตัวเข้ารหัส QR Code (@since 1.3.0)
DataMatrixEncoder	encode(string $data, array $options = []): Barcode2DData	ตัวเข้ารหัส Data Matrix (@since 1.3.0)
Pdf417Encoder	encode(string $data, array $options = []): Barcode2DData	ตัวเข้ารหัส PDF417 (@since 1.3.0)
BarcodeEncoderRegistry	createDefault(), register(), resolve(), has(), get(), registered()	รีจิสทรีตัวเข้ารหัสแบบ PSR-11 (@since 3.0.0)
BarcodeType / Barcode2DType	enum cases	การระบุรายการซิมโบโลยีที่รองรับ
GaloisField / GaloisFieldPrime	เลขคณิตบนฟิลด์จำกัด	การแก้ไขข้อผิดพลาดแบบ Reed-Solomon

เรียกใช้ composer docs:generate-api-php -- --module=Barcode เพื่อสร้างตาราง PHPDoc ฉบับเต็ม

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

แหล่งที่มา: 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->addPage();

$doc->write1DBarcode('4006381333931', BarcodeType::EAN13, x: 15, y: null, w: 60, h: 20);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: 40, w: 40, h: 40);

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

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

แปลงตัวเข้ารหัส 2D โดยตรงผ่านรีจิสทรี และจำกัดขอบเขตของเพย์โหลดก่อนเข้ารหัส

<?php

declare(strict_types=1);

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

use NextPDF\Barcode\Barcode2DType;
use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class TrackingCodeService
{
    private const int MAX_PAYLOAD = 512;

    public function __construct(
        private BarcodeEncoderRegistry $registry,
        private LoggerInterface $logger,
    ) {}

    /** @return \NextPDF\Barcode\Barcode2DData */
    public function encode(string $trackingId): \NextPDF\Barcode\Barcode2DData
    {
        if (strlen($trackingId) > self::MAX_PAYLOAD) {
            throw new \LengthException('Tracking payload exceeds the encode bound.');
        }

        try {
            $encoder = $this->registry->resolve(Barcode2DType::QRCode->value);

            return $encoder->encode($trackingId, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('Barcode encode failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

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

• เพย์โหลดแบบเส้นที่ละเมิดชุดอักขระหรือกฎเช็คดิจิตของซิมโบโลยีจะทำให้เกิด BarcodeException EAN/UPC จะคำนวณและต่อท้ายเช็คดิจิตให้ อย่าใส่เช็คดิจิตไว้ล่วงหน้า
• อาร์เรย์ $options ของ 2D เป็นค่าเฉพาะของแต่ละซิมโบโลยี เช่น ระดับการแก้ไขข้อผิดพลาดสำหรับ QR ตัวเข้ารหัสส่วนใหญ่จะละเว้นคีย์ที่ไม่รู้จัก ตรวจสอบแต่ละคีย์กับเอกสารของตัวเข้ารหัสนั้น
• Barcode2DType ระบุรายการซิมโบโลยีมากกว่าจำนวนซิมโบโลยีที่รุ่น core มีตัวเข้ารหัสมาให้ BarcodeEncoderRegistry::resolve() จะทำให้เกิดข้อยกเว้นสำหรับซิมโบโลยีที่ไม่ได้ลงทะเบียน แทนที่จะคืนค่าตัวแทนชั่วคราว
• ตัวเข้ารหัสที่ลงทะเบียนแล้วเป็นอินสแตนซ์ที่ใช้ร่วมกัน รักษาให้ตัวเข้ารหัสเหล่านี้ไม่มีสถานะนอกเหนือจากการกำหนดค่าในคอนสตรักเตอร์ สถานะแบบต่อการเรียกหนึ่งครั้งจะทำให้การเรนเดอร์พร้อมกันเสียหาย
• เพย์โหลดที่ยาวเกินไปจะทำให้ได้เมทริกซ์ที่หนาแน่นและใหญ่ขึ้น จำกัดความยาวของเพย์โหลดก่อนเข้ารหัสเพื่อหลีกเลี่ยงการปฏิเสธการให้บริการผ่านขนาดของสัญลักษณ์

ประสิทธิภาพ

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

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

เพย์โหลดของบาร์โค้ดมักมาจากแหล่งที่ไม่น่าเชื่อถือ เช่น uniform resource locator (URL) ที่สแกนมา หมายเลขซีเรียล หรือรหัสติดตาม ตัวเข้ารหัสจะเข้ารหัสไบต์ แต่ไม่ตีความไบต์เหล่านั้น QR Code ที่เข้ารหัส URL ที่เป็นอันตรายยังคงเป็น QR Code ที่ถูกต้อง ดังนั้นผู้บริโภคจึงเป็นผู้รับผิดชอบต่อความน่าเชื่อถือของเพย์โหลด จำกัดความยาวของเพย์โหลดก่อนเข้ารหัสเพื่อให้ขนาดของเมทริกซ์ ปริมาณงาน และขนาดของผลลัพธ์อยู่ภายในงบประมาณ ถือว่าข้อมูลใดๆ ที่ถอดรหัสจากบาร์โค้ดที่อื่นเป็นอินพุตที่ไม่น่าเชื่อถือเมื่อกลับเข้าสู่แอปพลิเคชันอีกครั้ง ดูแบบจำลองภัยคุกคามของเอนจินได้ที่ /modules/core/security/

ความสอดคล้อง

ข้อกล่าวอ้าง	มาตรฐาน	แหล่งอ้างอิง
สัญลักษณ์ QR Code เป็นไปตามข้อกำหนดซิมโบโลยีแบบเมทริกซ์ของ QR Code	ISO/IEC 18004	ซิมโบโลยี QR Code
สัญลักษณ์ Data Matrix เป็นไปตามข้อกำหนดซิมโบโลยีของ Data Matrix	ISO/IEC 16022	ซิมโบโลยี Data Matrix
สัญลักษณ์ PDF417 เป็นไปตามข้อกำหนดซิมโบโลยีของ PDF417	ISO/IEC 15438	ซิมโบโลยี PDF417
สัญลักษณ์ Code 128 เป็นไปตามข้อกำหนดซิมโบโลยีแบบเส้นของ Code 128	ISO/IEC 15417	ซิมโบโลยี Code 128
สัญลักษณ์ EAN/UPC เป็นไปตามข้อกำหนดซิมโบโลยีของ EAN/UPC	ISO/IEC 15420	ซิมโบโลยี EAN/UPC

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

ดูเพิ่มเติม

• Contracts / Barcode — อินเทอร์เฟซตัวเข้ารหัสที่คลาสเหล่านี้นำไปใช้งานจริง (SPI)
• โมดูล Graphics — เลเยอร์การวาดที่วาดเมทริกซ์ที่เข้ารหัสแล้ว
• โมดูล Document — write1DBarcode() / write2DBarcode() ฟาซาดระดับสูง
• ภาพรวมความสอดคล้อง
• แบบจำลองความปลอดภัยของเอนจิน