สร้างบาร์โค้ด GS1 Composite (CC-C carrier)

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

ความสามารถแบบ preview ที่เป็น opt-in — เปิดเป็นค่าเริ่มต้นปิด การรองรับ GS1 Composite เป็นคุณสมบัติ opt-in ที่ทดลอง composite ที่ ship เดียวคือ CC-C (full PDF417 carrier): Core ลงทะเบียนความสามารถ barcode.gs1-composite-cc-c และแพ็กเกจ Premium (nextpdf/pro) gate ตัวเข้ารหัสไว้หลังมัน ด้วย Core เพียง อย่างเดียว ความสามารถถูกลงทะเบียนแต่สถานะของมันคือ Unavailable ดังนั้นจึงไม่มี สิ่งใดถูกส่งออก CC-A และ CC-B ยังไม่พร้อมใช้งาน: คำขอเข้ารหัสตัวใดตัวหนึ่งจะ fail closed ด้วยข้อยกเว้นแบบมีชนิด (UnsupportedBarcodeFeature) นี่คือขอบเขต ของขอบเขตที่บันทึกไว้ ไม่ใช่ข้อบกพร่อง

สัญลักษณ์ GS1 Composite จับคู่องค์ประกอบเชิงเส้น (ตัวระบุไอเทมหลัก) กับองค์ประกอบ composite แบบ 2D (ข้อมูลขยาย เช่น batch หรือวันหมดอายุ) สูตรนี้แสดงวิธีที่ความสามารถ composite ถูกลงทะเบียนและแก้ไข สิ่งที่ Core จัดหา สิ่งที่ Premium เพิ่ม และจุดที่การ รองรับหยุดพอดี

การติดตั้ง

composer require nextpdf/core:^3

ตัวเข้ารหัส composite CC-C ต้องการแพ็กเกจ Premium:

composer require nextpdf/pro

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

NextPDF แก้ไข symbology ผ่าน capability registry ด้วยวิธีเดียวกับที่ โมดูล Barcode แก้ไขตัวเข้ารหัสใด ๆ ความสามารถ GS1 Composite หนึ่งอย่างถูกลงทะเบียนไว้ที่นั่น:

• barcode.gs1-composite-cc-c ถูกลงทะเบียนใน CapabilityRegistry ใน Core ภายใต้ระดับผลิตภัณฑ์ Pro มันคือ full PDF417 carrier (ISO/IEC 15438) สำหรับ องค์ประกอบ composite CC-C ตัวเข้ารหัส Pro ส่ง payload ผ่านตัวเข้ารหัส PDF417 หลัก ของ core ความสามารถถูก ลงทะเบียนเสมอ แต่ Available เฉพาะเมื่อมีการติดตั้ง Premium — ด้วย Core เพียงอย่างเดียว สถานะของมันคือ Unavailable ดังนั้นมันจึง ถูกลงทะเบียนแต่ไม่ทำงาน (opt-in, เปิดเป็นค่าเริ่มต้นปิด)

ไม่มีการลงทะเบียนความสามารถ CC-A หรือ CC-B องค์ประกอบ 2D แบบ CC-A/CC-B ที่ สอดคล้องต้องการ high-level encodation แบบ base-928 ตาม ISO/IEC 24723 Clause 5 บวกกับ carrier เฉพาะองค์ประกอบ และรีลีสนี้ไม่ได้นำเส้นทางนั้นมาใช้ ดังนั้นการโฆษณา ความสามารถ CC-A/CC-B จะเป็นการตั้งชื่อตัวเข้ารหัสที่ไม่สามารถส่งสัญลักษณ์ที่ถอดรหัส ได้ออกมา

ขอบเขต fail-closed — สิ่งที่ยังไม่พร้อมใช้งาน

CC-A และ CC-B จงใจไม่ถูก ship เป็น symbology ที่ใช้งานได้:

• CC-A — ไพรมิทิฟ radix แบบ base-928 ระดับล่าง (Base928Converter, codeword เท่านั้น) และตัวสร้าง binary-string ของ Clause-5 มีอยู่ภายใน แต่ high-level encodation แบบ CC-A ตาม ISO/IEC 24723 Clause 5 เต็มรูปแบบและ carrier เฉพาะ CC-A ยังไม่ถูกนำมาใช้ ดังนั้นจึงไม่มีสัญลักษณ์ CC-A ที่ใช้งานได้ถูกผลิตออกมา CompositeComponentA::encode() โยนข้อยกเว้นแบบมีชนิด UnsupportedBarcodeFeature เสมอ
• CC-B — องค์ประกอบ composite ความจุปานกลางก็ยังไม่ถูกนำมาใช้เช่นกัน; CompositeComponentB::encode() โยน UnsupportedBarcodeFeature เสมอ

เหล่านี้ fail closed: คำขอเข้ารหัสตัวใดตัวหนึ่งจะยกข้อยกเว้นแบบมีชนิดแทนที่จะส่ง สัญลักษณ์บางส่วนหรือผิด นี่คือเส้นแบ่งขอบเขตที่จงใจ ไม่ใช่ข้อบกพร่อง

เส้นทาง CC-C ที่ ship แล้วเป็นไปตามวินัย codeword-golden: codeword ที่สร้างขึ้นถูก ตรึงเทียบกับ golden และตรวจสอบข้ามด้วยตัวถอดรหัสอิสระ ดังนั้น stream ของ codeword CC-C จึงถูกตรวจสอบ ไม่ใช่เพียงผลิตออกมา ไม่มีการอ้างการรับรองแบบ end-to-end เทียบ กับมาตรฐาน GS1 Composite

พื้นผิวของ API

สัญลักษณ์ GS1 Composite แก้ไขผ่าน capability registry แทนที่จะเป็นเมท็อด facade ระดับบนสุดใหม่:

• NextPDF\Support\CapabilityRegistry — การค้นหาที่รายงานว่า barcode.gs1-composite-cc-c เป็น Available ในรุ่นปัจจุบันหรือไม่ ใช้ get('barcode.gs1-composite-cc-c')->status สำหรับการตัดสินความพร้อมใช้งาน; has() รายงานเพียงว่าความสามารถ ถูกลงทะเบียน (เป็นจริงแม้บนการติดตั้ง Core-only) ดังนั้นมันจึงไม่ใช่ gate ของความพร้อมใช้งาน
• ตัวเข้ารหัส composite CC-C จัดหาโดย nextpdf/pro และลงทะเบียนไว้หลังสัญญาตัว เข้ารหัสเดียวกับที่หน้า Contracts / Barcode บันทึกไว้
• ไม่มีตัวเข้ารหัส CC-A หรือ CC-B ให้เรียก คลาสองค์ประกอบ CC-A/CC-B fail closed ที่ encode()

รัน composer docs:generate-api-php -- --module=Barcode สำหรับตารางตัวเข้ารหัสที่ สร้างขึ้น

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

ตรวจสอบว่าความสามารถ CC-C carrier พร้อมใช้งาน ก่อนที่คุณจะพึ่งพามัน ด้วย Core เพียงอย่างเดียว มันถูกลงทะเบียนแต่ Unavailable; เมื่อติดตั้ง Premium มันเป็น Available Gate ที่สถานะ ไม่ใช่ที่ has() — has() เป็นจริงบนการติดตั้ง Core-only ด้วย เพราะความสามารถถูกลงทะเบียนเสมอ

<?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";
}

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

Gate ที่สถานะของความสามารถ และจัดการองค์ประกอบที่ไม่พร้อมใช้งานอย่างชัดเจน สัญลักษณ์ CC-C ที่ซื่อตรงหรือการปฏิเสธที่ชัดเจน — ไม่ใช่ composite ที่ผิด

<?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; ตัวเข้ารหัสที่อยู่หลังมัน ship ใน nextpdf/pro บนการติดตั้ง Core-only ความสามารถถูกลงทะเบียนแต่สถานะของมันคือ Unavailable Gate ที่ get(...)->status ไม่ใช่ที่ has() — has() เป็นจริงแม้บน Core-only เพราะรายการถูกลงทะเบียนเสมอ
• ไม่มีตัวเข้ารหัส CC-A ที่ใช้งานได้ ไพรมิทิฟ radix แบบ base-928 ระดับล่างมีอยู่ ภายใน แต่ high-level encodation แบบ CC-A ตาม ISO/IEC 24723 Clause 5 เต็มรูปแบบ และ carrier เฉพาะ CC-A ยังไม่ถูกนำมาใช้ ดังนั้นจึงไม่มีสัญลักษณ์ CC-A ถูกผลิต ออกมา
• CC-A และ CC-B fail closed encode() ของพวกมันโยนข้อยกเว้นแบบมีชนิด UnsupportedBarcodeFeature เสมอแทนที่จะส่งสัญลักษณ์บางส่วน นี่คือขอบเขตของ ขอบเขตที่บันทึกไว้ โดยตั้งใจ
• GS1 application identifier ยังใช้บังคับ องค์ประกอบเชิงเส้นบรรจุข้อมูลที่มี โครงสร้าง GS1 พร้อม prefix FNC1 เช่นเดียวกับใน สร้างบาร์โค้ด 1D และ 2D
• กำหนดขอบเขต payload payload composite ที่ใหญ่ขึ้นให้สัญลักษณ์ที่หนาแน่นขึ้น กำหนดขอบเขตความยาว payload ก่อนเข้ารหัส

ประสิทธิภาพ

การสร้าง codeword เป็นเชิงเส้นตามความยาว payload; การส่ง carrier เป็นเชิงเส้นตาม พื้นที่ matrix ไม่มีขั้นตอน rasterization — แต่ละ module เป็น path operator — ดังนั้น หน่วยความจำจึงคงที่ไม่ว่าสัญลักษณ์จะมีขนาดเท่าใด สูตรนี้อยู่ภายในงบประมาณ 1500 ms / 64 MB

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

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

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

ข้อความ	มาตรฐาน	ข้อ
องค์ประกอบ composite CC-C ที่ ship แล้วใช้ PDF417 carrier	ISO/IEC 15438 (PDF417)	§5
high-level encodation แบบ base-928 ของ CC-A คือวิธี Clause 5 ที่รีลีสนี้ไม่ได้นำมาใช้	ISO/IEC 24723 (GS1 Composite)	§5

นี่คือการนำมาใช้แบบ preview ที่ทดลองและเป็น opt-in Core ลงทะเบียนความสามารถ barcode.gs1-composite-cc-c ภายใต้ระดับ Pro; แพ็กเกจ Premium gate ตัวเข้ารหัส CC-C ซึ่งเปิดเป็นค่าเริ่มต้นปิดบนการติดตั้ง Core-only (สถานะ Unavailable) CC-A และ CC-B ยังไม่พร้อมใช้งาน — encode() ของพวกมัน fail closed ด้วยข้อยกเว้นแบบมีชนิด UnsupportedBarcodeFeature codeword CC-C ที่ ship แล้วถูกตรึงเทียบกับ golden และ ตรวจสอบข้ามด้วยตัวถอดรหัสอิสระ ไม่มีการอ้าง GA, ความสอดคล้อง หรือการรับรองแบบ end-to-end เทียบกับมาตรฐาน GS1 Composite และไม่มีการคัดลอกข้อความมาตรฐานซ้ำ

ดูเพิ่มเติม

• โมดูล Barcode
• สร้างบาร์โค้ด 1D และ 2D
• Contracts / Barcode