إنشاء رموز شريطية أحادية وثنائية الأبعاد في ملف PDF

لمحة سريعة

توضّح هذه الوصفة كيفية رسم الرموز الشريطية الأحادية البُعد (1⁨D⁩) والثنائية البُعد (2⁨D⁩) مباشرةً على صفحة بتنسيق المستندات المحمولة (⁨PDF⁩). توفّر سمة HasBarcodes في ⁨Core⁩ الدالتين write1DBarcode() وwrite2DBarcode(). ترسم كلتا الدالتين الرمز على هيئة معاملات مسار ⁨PDF⁩ أصلية في الصفحة الحالية، فينتج عنها محتوى متجهي بسيط وحتمي. تستند هذه الوصفة إلى examples/10-barcodes.php.

التثبيت

composer require nextpdf/core:^3

لا تحتاج إلى أي امتداد إضافي. فمُرمِّزات الرموز الشريطية مكتوبة بلغة ⁨PHP⁩ خالصة، ويرسم ⁨NextPDF⁩ الرموز باستخدام معامل المستطيل القياسي في ⁨PDF⁩ (⁨ISO 32000-2⁩ §8.5).

نظرة عامة مفاهيمية

يُرسَم الرمز الشريطي بدلًا من تضمينه بوصفه صورة. الحمولة هي البيانات التي ترمّزها، مثل رقم منتج أو عنوان ويب.

تُرمِّز write1DBarcode() الحمولة وفق نمط ⁨bar/space⁩ لنوع BarcodeType المختار، ثم تُصدِر سلسلة من المستطيلات المملوءة. تبني write2DBarcode() مصفوفة وحدات لنوع Barcode2DType المختار، وتُصدِر مستطيلًا مملوءًا واحدًا لكل وحدة داكنة. يستخدم ⁨Data Matrix⁩ و⁨QR Code⁩ تصحيح الأخطاء بطريقة ⁨Reed-Solomon⁩، فيستطيع الماسح استعادة البيانات حتى إذا تلف جزء من الرمز.

كل وحدة هي مسار re … f حتمي بلا مصدر عشوائية، فمحتوى الرمز الشريطي نفسه قابل لإعادة الإنتاج بالكامل. ملف تعريف إعادة الإنتاج هو structural لأن المستند المحيط ما زال يحمل عناصر خاصة بكل عملية حفظ: السمة /ID في المُذيَّل، إضافةً إلى الطابعين الزمنيين /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

نظام الترميز هو معيار للرموز الشريطية يحدد كيفية تحويل البيانات إلى أشرطة أو وحدات. يعدد BarcodeType أنظمة الترميز الأحادية البُعد (C128، EAN13، UPCA، I25، CODABAR، ISBN، GS1_128، …)، ويعدد Barcode2DType أنظمة الترميز الثنائية البُعد (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)

الحالات الحدّية والمزالق

صلاحية الحمولة خاصة بنظام الترميز. يتوقع EAN13 ‏12 أو 13 رقمًا. تؤدي الحمولة غير الصالحة إلى إطلاق استثناء قبل أن يكتب ⁨NextPDF⁩ أي محتوى. ولكلٍّ من UPCA وISBN وISSN قواعدها الخاصة في الطول ورقم التحقق.
x/y اختياريان. عند حذفهما، يُوضَع الرمز الشريطي عند موضع المؤشر الحالي. مرّر إحداثيات صريحة للحصول على تخطيط متوقَّع.
w = 0 يضبط الحجم تلقائيًا. يتيح العرض الصفري للمُرمِّز اختيار عرض وحدة طبيعي. مرّر عرضًا موجبًا ليلائم مربعًا ثابتًا.
مستوى تصحيح الأخطاء الثنائي البُعد. القيمة الافتراضية في write2DBarcode() هي ecLevel: 'L'، وهي أدنى مستوى. ارفعه ('M'، 'Q'، 'H') لرموز ⁨QR Code⁩ التي يجب أن تصمد أمام تلف الطباعة. تزيد المستويات الأعلى حجم المصفوفة.
معرّفات تطبيق ⁨GS1.⁩ مرّر gs1: true إلى write2DBarcode()، أو استخدم BarcodeType::GS1_128، للبيانات المنظَّمة وفق ⁨GS1⁩ مع بادئة ⁨FNC1.⁩
تُنشأ صفحة ضمنيًا. عند استدعاء دالة رمز شريطي قبل addPage()، يضيف ⁨NextPDF⁩ صفحة أولًا. هذا مفيد، لكن استدعِ addPage() صراحةً عندما تكون هندسة الصفحة مهمة.

الأداء

تعقيد الترميز هو ⁨O⁩(⁨payload length⁩) للأحادي البُعد و⁨O⁩(⁨matrix area⁩) للثنائي البُعد، وكلاهما يعمل عادةً في نطاق الميكروثواني. تمثَّل كل وحدة بمعامل مسار re … f واحد، فيضيف ⁨QR Code⁩ الكثيف بضعة كيلوبايتات إلى دفق المحتوى. لا توجد خطوة تنقيط، فتبقى الذاكرة ثابتة بغضّ النظر عن حجم الرمز. تبقى الوصفة بهامش آمن ضمن ميزانية 1500 ⁨ms⁩ / 64 ⁨MB.⁩

ملاحظات أمنية

يحمل الرمز الشريطي أي حمولة تمرّرها، لذا عامِل قيمة الرمز الشريطي مثل أي إدخال آخر غير موثوق في الطرف المستهلك. لا توقّع المكتبة الحمولة ولا تتحقق من أصالتها. الرمز الثنائي البُعد ليس تشفيرًا: يستطيع أي شخص يملك ماسحًا قراءته.

المطابقة

العبارة	المواصفة	البند
تُرسَم وحدات الرمز الشريطي باستخدام معامل إنشاء مسار المستطيل.	⁨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⁩ ترميزات أنظمة الترميز المُستشهَد بها، لكنه لا يدّعي شهادة رسمية بالمطابقة لمعايير الرموز الشريطية. وثائق مجموعة أنظمة ترميز الرموز الشريطية مقيَّدة بالترخيص عند المستوى ⁨Tier C.⁩ تستخدم الاستشهادات معرّفات ⁨clause-id⁩ وreference_id فقط، ولا يُعاد إنتاج أي نص معياري.