إنشاء رموز GS1 الشريطية المركّبة (حامل CC-C)

لمحة سريعة

قدرة معاينة اختيارية — مُعطَّلة افتراضيًا. دعم GS1 المركّب ميزة تجريبية اختيارية. والمركّب المشحون الوحيد هو CC-C (حامل ⁨PDF⁩417 الكامل): تُسجِّل Core القدرة barcode.gs1-composite-cc-c وتُبوِّب حزمة Premium (nextpdf/pro) المُرمِّز خلفها. ومع Core وحدها، تكون القدرة مُسجَّلة لكن حالتها Unavailable، فلا يُصدَر شيء. وCC-A وCC-B غير متوفّرين بعد: أي طلب لترميز أحدهما يُغلَق بأمان مع استثناء مُحدَّد النوع (UnsupportedBarcodeFeature). وهذا حدّ نطاق مُوثَّق، لا خلل.

يُقرِن رمز GS1 المركّب مكوّنًا خطّيًا (مُعرِّف العنصر الأساسي) بمكوّن مركّب ثنائي الأبعاد (بيانات مُمتدّة مثل دفعة أو انتهاء صلاحية). تُبيّن هذه الوصفة كيف تُسجَّل القدرة المركّبة وتُحلّ، وما تُوفِّره Core، وما تُضيفه Premium، وأين يتوقّف الدعم بالضبط.

التثبيت

composer require nextpdf/core:^3

يتطلّب مُرمِّز CC-C المركّب حزمة Premium:

composer require nextpdf/pro

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

يُحلّ ⁨NextPDF⁩ أي رمزية عبر سجلّ القدرات، بالطريقة نفسها التي تحلّ بها وحدة الرموز الشريطية أي مُرمِّز. وقدرة GS1 مركّبة واحدة مُسجَّلة هناك:

• barcode.gs1-composite-cc-c مُسجَّلة في CapabilityRegistry في Core، تحت طبقة المنتج Pro. وهي حامل ⁨PDF⁩417 الكامل (ISO/IEC 15438) لمكوّن CC-C المركّب. ويوجّه مُرمِّز Pro الحمولة عبر مُرمِّز ⁨PDF⁩417 الأساسي القانوني في النواة. والقدرة مُسجَّلة دائمًا لكنها Available فقط عند تثبيت Premium — ومع Core وحدها تكون حالتها Unavailable، فهي مُسجَّلة لكنها خاملة (اختيارية، مُعطَّلة افتراضيًا).

لا تُسجَّل أي قدرة CC-A أو CC-B. فمكوّن ثنائي الأبعاد CC-A/CC-B مطابق يتطلّب ترميز ISO/IEC 24723 البند 5 العالي المستوى بالأساس 928 بالإضافة إلى حامل خاص بالمكوّن، وهذا الإصدار لا يُطبِّق ذلك المسار، فإعلان قدرة CC-A/CC-B سيُسمّي مُرمِّزًا لا يمكنه إصدار رمز قابل للقراءة.

حدّ الإغلاق الآمن — ما هو غير متوفّر بعد

CC-A وCC-B غير مشحونَين عمدًا كرمزيتَين قابلتَين للاستخدام:

• CC-A — توجد داخليًا بنية أوّلية للأساس 928 منخفضة المستوى (Base928Converter، كلمات رمز فقط) وباني سلسلة ثنائية وفق البند 5، لكن ترميز CC-A العالي المستوى الكامل وفق ISO/IEC 24723 البند 5 والحامل الخاص بـ CC-A غير مُطبَّقَين، فلا يُنتَج أي رمز CC-A قابل للاستخدام. وCompositeComponentA::encode() يطرح دائمًا استثناء UnsupportedBarcodeFeature المُحدَّد النوع.
• CC-B — المكوّن المركّب متوسّط السعة غير مُطبَّق كذلك؛ وCompositeComponentB::encode() يطرح دائمًا UnsupportedBarcodeFeature.

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

يتبع مسار CC-C المشحون انضباط الكلمات-الرمز الذهبية: فكلماته الرمزية المُولَّدة مُثبَّتة مقابل ملف ذهبي ومُتحقَّق منها بمُفكِّك مستقلّ، فيكون تدفّق كلمات رمز CC-C مُتحقَّقًا منه، لا مُنتَجًا فحسب. ولا يُدَّعى أي اعتماد شامل من طرفٍ إلى طرف مقابل معيار GS1 المركّب.

سطح الـ ⁨API⁩

تُحلّ رموز GS1 المركّبة عبر سجلّ القدرات لا عبر دالة واجهة عُليا جديدة في المستوى الأعلى:

• NextPDF\Support\CapabilityRegistry — البحث الذي يُبلِغ عمّا إذا كانت barcode.gs1-composite-cc-c بحالة Available في الإصدار الحالي. استخدم get('barcode.gs1-composite-cc-c')->status لقرار التوفّر؛ أما has() فيُبلِغ فقط بأن القدرة مُسجَّلة (صحيح حتى على تثبيتات Core فقط)، فهو ليس بوّابة التوفّر.
• يُورِّد nextpdf/pro مُرمِّز CC-C المركّب ويُسجَّل خلف عقد المُرمِّز نفسه الذي تُوثِّقه صفحة العقود / الرموز الشريطية.
• لا يوجد مُرمِّز CC-A أو CC-B لاستدعائه. وأصناف مكوّنات CC-A/CC-B تُغلَق بأمان عند encode().

شغِّل composer docs:generate-api-php -- --module=Barcode للحصول على جدول المُرمِّزات المُولَّد.

نموذج برمجي — بداية سريعة

تحقّق من أن قدرة حامل CC-C متوفّرة قبل أن تعتمد عليها. مع Core وحدها تكون مُسجَّلة لكن Unavailable؛ ومع تثبيت Premium تكون Available. بوِّب على الحالة، لا على has() — فـ has() صحيح على تثبيت Core فقط أيضًا، لأن القدرة مُسجَّلة دائمًا.

<?php

declare(strict_types=1);

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

use NextPDF\Support\CapabilityRegistry;
use NextPDF\Support\CapabilityStatus;

$registry = CapabilityRegistry::getInstance();

$capability = $registry->get('barcode.gs1-composite-cc-c');

if ($capability->status === CapabilityStatus::Available) {
    echo "CC-C composite carrier is available (Premium present)\n";
} else {
    echo "CC-C composite carrier needs nextpdf/pro\n";
}

نموذج برمجي — إنتاجي

بوِّب على حالة القدرة، وعامِل المكوّنات غير المتوفّرة صراحةً. رمز CC-C أمين أو رفض واضح — لا مركّب خاطئ أبدًا.

<?php

declare(strict_types=1);

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

use NextPDF\Support\CapabilityRegistry;
use NextPDF\Support\CapabilityStatus;

final readonly class CompositeLabelService
{
    public function __construct(private CapabilityRegistry $registry) {}

    /**
     * Assert that the only shipped GS1 Composite (CC-C) is available before use.
     *
     * The capability is opt-in and default-OFF: on a Core-only install it is
     * registered but its status is Unavailable, so check the status — not has().
     */
    public function assertCompositeAvailable(): void
    {
        $status = $this->registry->get('barcode.gs1-composite-cc-c')->status;

        if ($status !== CapabilityStatus::Available) {
            // Core-only install. The CC-C encoder needs Premium. Fail fast with
            // a clear upgrade message rather than emitting a degraded symbol.
            throw new \RuntimeException(
                'GS1 Composite CC-C requires nextpdf/pro.',
            );
        }
    }

    // CC-A and CC-B are NOT yet available. Their component classes fail closed:
    // calling encode() always throws NextPDF\Pro\Barcode\Gs1Composite\
    // UnsupportedBarcodeFeature. There is no runnable CC-A/CC-B encode path —
    // CC-C is the only shipped GS1 Composite symbology. Do not call encode() on
    // CC-A/CC-B expecting a symbol.
    public function note(): string
    {
        return 'CC-A and CC-B are not available; use CC-C.';
    }
}

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

• CC-C يحتاج Premium ليكون متوفّرًا، وهو مُعطَّل افتراضيًا. تُسجِّل Core القدرة تحت طبقة Pro؛ والمُرمِّز خلفها يُشحَن في nextpdf/pro. وعلى تثبيت Core فقط تكون القدرة مُسجَّلة لكن حالتها Unavailable. بوِّب على get(...)->status، لا على has() — فـ has() صحيح حتى على Core فقط لأن المدخل مُسجَّل دائمًا.
• لا يوجد مُرمِّز CC-A قابل للاستخدام. توجد بنية أوّلية للأساس 928 منخفضة المستوى داخليًا، لكن ترميز CC-A العالي المستوى الكامل وفق ISO/IEC 24723 البند 5 والحامل الخاص بـ CC-A غير مُطبَّقَين، فلا يُنتَج أي رمز CC-A.
• CC-A وCC-B يُغلَقان بأمان. encode() لديهما يطرح دائمًا استثناء UnsupportedBarcodeFeature المُحدَّد النوع بدلًا من إصدار رمز جزئي. وهذا حدّ نطاق مُوثَّق، عن قصد.
• مُعرِّفات تطبيق GS1 لا تزال تنطبق. يحمل المكوّن الخطّي بيانات مُهيكَلة بـ GS1 مع بادئة FNC1، كما في توليد رموز شريطية أحادية وثنائية الأبعاد.
• حُدّ الحمولة. حمولة مركّبة أكبر تُنتج رمزًا أكثف. حُدّ طول الحمولة قبل الترميز.

الأداء

توليد الكلمات الرمزية خطّيٌّ في طول الحمولة؛ وإصدار الحامل خطّيٌّ في مساحة المصفوفة. ولا توجد خطوة تنقيط — فكل وحدة هي معامل مسار — لذا تبقى الذاكرة مسطّحة بصرف النظر عن حجم الرمز. وتبقى الوصفة داخل ميزانية الـ 1500 مللي ثانية / 64 ميغابايت.

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

يحمل الرمز المركّب أي حمولة تمرّرها؛ عامِل القيمة على أنها غير موثوقة في الجانب المستهلِك. وتُرمِّز المُرمِّزات بايتات ولا تُصادِق عليها. حُدّ طول الحمولة قبل الترميز لإبقاء حجم الرمز والعمل ضمن الميزانية.

المطابقة

العبارة	المواصفة	البند
يستخدم مكوّن CC-C المركّب المشحون حامل PDF417.	ISO/IEC 15438 (PDF417)	§5
ترميز CC-A العالي المستوى بالأساس 928 هو طريقة البند 5 التي لا يُطبِّقها هذا الإصدار.	ISO/IEC 24723 (GS1 Composite)	§5

هذا تطبيق معاينة تجريبي اختياري. تُسجِّل Core القدرة barcode.gs1-composite-cc-c تحت طبقة Pro؛ وتُبوِّب حزمة Premium مُرمِّز CC-C، وهو مُعطَّل افتراضيًا على تثبيت Core فقط (الحالة Unavailable). وCC-A وCC-B غير متوفّرين بعد — فـ encode() لديهما يُغلَق بأمان مع استثناء UnsupportedBarcodeFeature المُحدَّد النوع. وكلمات CC-C الرمزية المشحونة مُثبَّتة مقابل ملف ذهبي ومُتحقَّق منها بمُفكِّك مستقلّ. ولا يُدَّعى أي توفّر عام أو مطابقة أو اعتماد شامل من طرفٍ إلى طرف مقابل معيار GS1 المركّب، ولا يُعاد إنتاج أي نص معياري.

انظر أيضًا

• وحدة الرموز الشريطية
• توليد رموز شريطية أحادية وثنائية الأبعاد
• العقود / الرموز الشريطية