สร้างบาร์โค้ด 1D และ 2D ใน PDF

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

สูตรนี้ใช้สำหรับวาดบาร์โค้ดหนึ่งมิติ (1D) และสองมิติ (2D) ลงบนหน้า Portable Document Format (PDF) โดยตรง trait HasBarcodes ของ Core มีเมท็อด write1DBarcode() และ write2DBarcode() ให้ใช้งาน เมท็อดทั้งสองวาดสัญลักษณ์เป็นตัวดำเนินการเส้นทาง (path operator) เนทีฟของ PDF บนหน้าปัจจุบัน ผลลัพธ์จึงเป็นเนื้อหาเวกเตอร์ที่เรียบง่ายและให้ผลลัพธ์แน่นอน สูตรนี้อ้างอิงจาก examples/10-barcodes.php

การติดตั้ง

composer require nextpdf/core:^3

ไม่ต้องติดตั้งส่วนขยายเพิ่มเติม ตัวเข้ารหัสบาร์โค้ดเป็น PHP ล้วน และ NextPDF วาดสัญลักษณ์ด้วยตัวดำเนินการสี่เหลี่ยมผืนผ้ามาตรฐานของ PDF (ISO 32000-2 §8.5)

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

บาร์โค้ดจะถูกวาดขึ้น ไม่ได้ถูกฝังเป็นรูปภาพ payload คือข้อมูลที่ต้องการเข้ารหัส เช่น หมายเลขสินค้าหรือที่อยู่เว็บ

write1DBarcode() เข้ารหัส payload เป็นรูปแบบ bar/space สำหรับ BarcodeType ที่เลือก จากนั้นส่งออกลำดับของสี่เหลี่ยมผืนผ้าที่เติมสี write2DBarcode() สร้างเมทริกซ์โมดูลสำหรับ Barcode2DType ที่เลือก และส่งออกสี่เหลี่ยมผืนผ้าที่เติมสีหนึ่งรายการสำหรับแต่ละโมดูลสีเข้ม Data Matrix และ QR Code ใช้การแก้ไขข้อผิดพลาดแบบ Reed-Solomon เครื่องสแกนจึงสามารถกู้คืนข้อมูลได้แม้บางส่วนของสัญลักษณ์เสียหาย

ทุกโมดูลเป็นเส้นทาง re … f ที่ให้ผลลัพธ์แน่นอนโดยไม่มีแหล่งสุ่ม เนื้อหาบาร์โค้ดจึงทำซ้ำได้อย่างสมบูรณ์ โปรไฟล์การทำซ้ำเป็นแบบ structural เนื่องจากเอกสารโดยรอบยังมีอะตอมเฉพาะต่อการบันทึกแต่ละครั้ง ได้แก่ /ID ใน trailer รวมถึงการประทับเวลา /CreationDate และ /ModDate ฮาร์เนสจะเปรียบเทียบโครงสร้างที่ผ่านการนอร์มัลไลซ์ด้วย qpdf โดยตัดอะตอมเหล่านั้นออก

โครงสร้าง API

NextPDF\Core\Concerns\HasBarcodes (ผสานเข้าใน Document):

write1DBarcode(string $code, BarcodeType $type, ?float $x = null, ?float $y = null, float $w = 0, float $h = 30, float $barWidth = 0.4, bool $skipZeroWidthBars = true): static
write2DBarcode(string $code, Barcode2DType $type, ?float $x = null, ?float $y = null, float $w = 0, float $h = 0, float $moduleSize = 1.0, string $ecLevel = 'L', ?int $mask = null, ?int $version = null, bool $gs1 = false, bool $dmre = false, bool $rectangular = false): static

symbology คือมาตรฐานบาร์โค้ดที่กำหนดวิธีแปลงข้อมูลเป็นแท่งหรือโมดูล BarcodeType ระบุ symbology แบบ 1D (C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …) และ Barcode2DType ระบุ symbology แบบ 2D (QRCode, DataMatrix, PDF417, HanXin, MicroQR, …)

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

<?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 Quick Start');
$doc->addPage();

$doc->write1DBarcode('NEXTPDF-2026', BarcodeType::C128, x: 15, y: 30, w: 80, h: 20);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: 60, w: 40, h: 40);

$doc->save(__DIR__ . '/barcodes.pdf');
echo "Wrote barcodes.pdf\n";

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

ด้านล่างเป็นตัวอย่างฉบับสมบูรณ์ที่รันผ่านฮาร์เนสได้ และสะท้อนเนื้อหาของ examples/10-barcodes.php โค้ดจะเขียน PDF ไปยังพาธที่ฮาร์เนสกำหนดผ่าน NEXTPDF_COOKBOOK_OUTPUT และจะใช้ไฟล์ในเครื่องแทนเมื่อรันด้วยตนเอง ดังนั้นฮาร์เนสสำหรับการทำซ้ำจึงรันได้สองครั้งและยืนยันว่าโครงสร้างเหมือนกันทุกประการ โครงสร้างจะผ่านการนอร์มัลไลซ์ด้วย qpdf โดยตัด /ID และอะตอมการประทับเวลาเฉพาะต่อการบันทึกแต่ละครั้งออก

<?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', 'B', 18);
$doc->cell(0, 12, 'Barcode Examples', newLine: true);
$doc->ln(5);

// --- 1D barcodes ---
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, '1D Barcodes', newLine: true);
$doc->ln(3);

$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, 'EAN-13:', newLine: true);
$doc->write1DBarcode('4006381333931', BarcodeType::EAN13, x: 15, y: null, w: 60, h: 20);
$doc->ln(28);

// --- 2D barcodes ---
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, '2D Barcodes', newLine: true);
$doc->ln(3);

$doc->setFont('helvetica', '', 10);
$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->ln(48);

$doc->cell(0, 6, 'DataMatrix:', newLine: true);
$doc->write2DBarcode('NextPDF-DM-2026', Barcode2DType::DataMatrix, x: 15, y: null, w: 30, h: 30);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/barcodes.pdf');

echo "Wrote barcodes PDF (Code 128, EAN-13, QR Code, DataMatrix)\n";

ผลลัพธ์ที่คาดหวัง:

Wrote barcodes PDF (Code 128, EAN-13, QR Code, DataMatrix)

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

ความถูกต้องของ payload ขึ้นอยู่กับแต่ละ symbology EAN13 ต้องการตัวเลข 12 หรือ 13 หลัก payload ที่ไม่ถูกต้องจะส่งข้อยกเว้นก่อนที่ NextPDF จะเขียนเนื้อหาใดๆ UPCA, ISBN และ ISSN มีกฎความยาวและเลขตรวจสอบของตนเอง
x/y เป็นค่าที่ไม่บังคับ เมื่อไม่ได้ระบุค่าเหล่านี้ บาร์โค้ดจะถูกวางที่ตำแหน่งเคอร์เซอร์ปัจจุบัน ระบุพิกัดให้ชัดเจนเพื่อให้คาดการณ์เค้าโครงได้
w = 0 ปรับขนาดอัตโนมัติ ความกว้างเป็นศูนย์ทำให้ตัวเข้ารหัสเลือกความกว้างตามธรรมชาติของโมดูล ระบุค่าความกว้างที่เป็นบวกเพื่อให้พอดีกับกล่องขนาดคงที่
ระดับการแก้ไขข้อผิดพลาดแบบ 2D write2DBarcode() ใช้ค่าเริ่มต้นเป็น ecLevel: 'L' ซึ่งเป็นระดับต่ำสุด เพิ่มระดับ ('M', 'Q', 'H') สำหรับ QR Code ที่ต้องทนทานต่อความเสียหายจากการพิมพ์ ระดับที่สูงขึ้นจะทำให้เมทริกซ์มีขนาดใหญ่ขึ้น
ตัวระบุการใช้งานของ GS1 ส่ง gs1: true ให้กับ write2DBarcode() หรือใช้ BarcodeType::GS1_128 สำหรับข้อมูลที่มีโครงสร้างตาม GS1 พร้อมคำนำหน้า FNC1
หน้าถูกสร้างขึ้นโดยปริยาย เมื่อเรียกเมท็อดบาร์โค้ดก่อน addPage() NextPDF จะเพิ่มหน้าให้ก่อน วิธีนี้สะดวก แต่ควรเรียก addPage() อย่างชัดเจนเมื่อรูปทรงของหน้ามีความสำคัญ

ประสิทธิภาพ

การเข้ารหัสเป็น O(payload length) สำหรับ 1D และ O(matrix area) สำหรับ 2D และทั้งสองแบบใช้เวลาในระดับไมโครวินาที แต่ละโมดูลคือตัวดำเนินการเส้นทาง re … f หนึ่งตัว ดังนั้น QR Code ที่หนาแน่นจึงเพิ่มสตรีมเนื้อหาเพียงไม่กี่กิโลไบต์ ไม่มีขั้นตอนการแรสเตอร์ไรซ์ หน่วยความจำจึงคงที่ไม่ว่าสัญลักษณ์จะมีขนาดเท่าใด สูตรนี้ยังอยู่ภายในงบประมาณ 1500 ms / 64 MB อย่างเหลือเฟือ

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

บาร์โค้ดบรรจุ payload ใดๆที่ส่งเข้าไป ดังนั้นฝั่งที่รับไปใช้งานควรปฏิบัติต่อค่าบาร์โค้ดเช่นเดียวกับอินพุตอื่นๆที่ไม่น่าเชื่อถือ ไลบรารีไม่ลงลายเซ็นและไม่ตรวจสอบความถูกต้องของ payload สัญลักษณ์ 2D ไม่ใช่การเข้ารหัสลับ: ผู้ที่มีเครื่องสแกนสามารถอ่านได้

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

ข้อความระบุ	ข้อกำหนด	ข้อ
โมดูลบาร์โค้ดถูกวาดด้วยตัวดำเนินการสร้างเส้นทางสี่เหลี่ยมผืนผ้า	ISO 32000-2	§8.5
อักขระสัญลักษณ์ของ Code 128 ใช้โครงสร้างองค์ประกอบ bar/space ที่กำหนดไว้	ISO/IEC 15417	§4.3.1
สัญลักษณ์ Data Matrix ใช้การแก้ไขข้อผิดพลาดแบบ Reed-Solomon	ISO/IEC 16022	§7.6.1
ข้อมูล QR Code ถูกแบ่งออกเป็นบล็อกการแก้ไขข้อผิดพลาด	ISO/IEC 18004	§7.5.2

NextPDF ใช้งานการเข้ารหัส symbology ตามแหล่งอ้างอิงที่ระบุ แต่ไม่ได้อ้างว่าผ่านการรับรองอย่างเป็นทางการตามมาตรฐานบาร์โค้ด เอกสารในคลังข้อมูล symbology ของบาร์โค้ดถูกจำกัดสิทธิ์การใช้งานไว้ที่ Tier C การอ้างอิงจึงใช้เฉพาะตัวชี้แบบ clause-id และ reference_id และไม่นำข้อความจากมาตรฐานมาแสดงซ้ำ