الباركود: مُرمِّزات للرموز الخطية وثنائية الأبعاد

لمحة سريعة

توفّر وحدة الباركود طبقة تنفيذ الرموز. فهي تُرمِّز الرموز الخطية (⁨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

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

يحوّل مُرمِّز الباركود سلسلة الحمولة إلى مصفوفة وحدات ثنائية الأبعاد (2⁨D⁩) أو إلى تسلسل خطوط أحادي البُعد (1⁨D⁩) يرسمه الكاتب كرسومات ضمن صيغة المستند المحمول (⁨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 يصف نمط الخطوط.

تُنفِّذ المُرمِّزات ثنائية الأبعاد، QrEncoder وDataMatrixEncoder وPdf417Encoder، الواجهة BarcodeEncoderInterface وتُرجِع مصفوفة Barcode2DData. ويُعدِّد Barcode2DType الرموز المصفوفية التي يتعرّف عليها المحرّك، بما فيها ⁨QR Code⁩ و⁨Data Matrix⁩ و⁨PDF417.⁩ كما تُعدَّد رموز إضافية مثل ⁨Micro QR⁩ و⁨rMQR⁩ و⁨GS1 DataBar⁩ و⁨Han Xin⁩ لأغراض توجيه السجل. وتعتمد مجموعة المُرمِّزات التي تدعم كل رمز على الإصدار. يُحسَب تصحيح أخطاء المصفوفة على حقل ⁨Galois.⁩ ويوفّر GaloisField وGaloisFieldPrime حساب ⁨Reed-Solomon⁩ المشترك بين مُرمِّزات ⁨QR⁩ و⁨Data Matrix⁩ و⁨PDF417.⁩

BarcodeEncoderRegistry هو أداة البحث. وهو يُنفِّذ الواجهة ContainerInterface الخاصة بتوصية معايير ⁨PHP⁩ رقم 11 (⁨PSR-11⁩)، ويوفّر التسجيل الافتراضي عبر createDefault()، ويحلّ الرمز إلى مُرمِّزه عبر resolve(). ونادراً ما يصل كود التطبيق إلى مُرمِّز مباشرةً. تُسمّي واجهة Document::write1DBarcode() / write2DBarcode() رفيعة المستوى رمزاً، فيوفّر السجل المُرمِّز المناسب. المحرّك الخطي هو @since 1.0.0. المُرمِّزات ثنائية الأبعاد هي @since 1.3.0. السجل هو @since 3.0.0.

واجهة البرمجة

الصنف	الأعضاء الرئيسية	الدور
`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`	حالات التعداد	تعدادات الرموز المدعومة
`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');

مثال برمجي — للإنتاج

حُلّ مُرمِّزاً ثنائي الأبعاد مباشرةً عبر السجل، وقيِّد الحمولة قبل الترميز.

<?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 ثنائية الأبعاد خاصة بكل رمز، مثل مستوى تصحيح الأخطاء لـ ⁨QR.⁩ تتجاهل معظم المُرمِّزات المفاتيح غير المعروفة. تحقّق من كل مفتاح مقابل وثائق المُرمِّز نفسه.
يُعدِّد Barcode2DType رموزاً أكثر مما يشحن إصدار الجوهر مُرمِّزات لها. يثير BarcodeEncoderRegistry::resolve() استثناءً لرمز غير مُسجَّل بدلاً من إرجاع عنصر نائب.
المُرمِّزات المُسجَّلة نُسخ مشتركة. حافظ على كونها عديمة الحالة فيما يتجاوز إعداد المُنشئ. فالحالة الخاصة بكل استدعاء تُفسد عمليات العرض المتزامنة.
تنتج الحمولة المفرطة الطول مصفوفة أكثر كثافة وأكبر حجماً. قيِّد طول الحمولة قبل الترميز لتفادي حجب الخدمة عبر حجم الرمز.

الأداء

تتناسب تكلفة الترميز مع طول الحمولة وحجم المصفوفة، لا مع بحث السجل الذي تعقيده ⁨O⁩(1). تُرمَّز حمولة ⁨Code 128⁩ قصيرة في ميكروثوانٍ. وأثقل الحالات هي ⁨QR Code⁩ كثيف مع تصحيح أخطاء عالٍ. تبقى صفحة المثال متعددة الرموز ضمن ميزانية 1500 ⁨ms⁩ للزمن الكلي / 64 ⁨MB⁩ للذروة. ملف إعادة الإنتاج هو bitwise. وتنتج الحمولة والخيارات نفسها دائماً مصفوفة الوحدات نفسها والبايتات المرسومة نفسها.

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

كثيراً ما تأتي حمولات الباركود من مصادر غير موثوقة: محدّد موقع موارد موحّد (⁨URL⁩) مَمسوح، أو رقم تسلسلي، أو رمز تتبّع. تُرمِّز المُرمِّزات البايتات ولا تفسّرها. ويظلّ ⁨QR Code⁩ الذي يُرمِّز عنوان ⁨URL⁩ خبيثاً رمز ⁨QR⁩ صالحاً، فالمستهلك هو المسؤول عن الثقة بالحمولة. قيِّد طول الحمولة قبل الترميز لإبقاء حجم المصفوفة والعمل وحجم المخرجات ضمن الميزانية. عامِل أي بيانات مفكوكة من باركود في موضع آخر بوصفها مدخلات غير موثوقة عندما تعود إلى التطبيق. راجع نموذج تهديدات المحرّك في /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⁩).
وحدة الرسومات — طبقة الرسم التي ترسم المصفوفة المُرمَّزة.
وحدة المستند — واجهة write1DBarcode() / write2DBarcode() رفيعة المستوى.
نظرة عامة على المطابقة
نموذج أمان المحرّك