바코드: 1D 및 2D 심볼로지 인코더

한눈에 보기

바코드 모듈은 심볼로지 구현 계층입니다. 선형 심볼로지(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

개념 개요

바코드 인코더는 페이로드 문자열을 문서 작성기가 PDF 그래픽으로 그릴 수 있는 모듈 행렬(2D) 또는 막대 시퀀스(1D)로 변환합니다. 이 모듈은 구체적인 인코더를 제공합니다.

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 값 객체를 반환합니다.

2D 인코더 — QrEncoder, DataMatrixEncoder, Pdf417Encoder —는 BarcodeEncoderInterface를 구현하고 Barcode2DData 행렬을 반환합니다. Barcode2DType은 엔진이 인식하는 행렬 심볼로지를 열거하며, QR Code, Data Matrix, PDF417을 포함합니다. Micro QR, rMQR, GS1 DataBar, Han Xin과 같은 추가 심볼로지는 레지스트리 라우팅을 위해 열거됩니다. 각 심볼로지를 뒷받침하는 인코더 집합은 에디션에 따라 달라집니다. 행렬 오류 정정은 Galois 체에서 계산됩니다. GaloisField와 GaloisFieldPrime은 QR, Data Matrix, PDF417 인코더가 공유하는 Reed-Solomon 산술을 제공합니다.

BarcodeEncoderRegistry는 조회 역할을 합니다. 이 클래스는 PSR-11 ContainerInterface를 구현하고, createDefault()를 통해 기본 등록을 제공하며, resolve()로 심볼로지를 해당 인코더로 해석합니다. 애플리케이션 코드가 인코더에 직접 접근하는 경우는 드뭅니다. 상위 수준의 Document::write1DBarcode() / write2DBarcode() 파사드에서 심볼로지를 지정하면 레지스트리가 인코더를 공급합니다. 1D 엔진은 @since 1.0.0입니다. 2D 인코더는 @since 1.3.0입니다. 레지스트리는 @since 3.0.0입니다.

API 표면

클래스	주요 멤버	역할
`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`	enum 케이스	지원되는 심볼로지 열거형
`GaloisField` / `GaloisFieldPrime`	유한체 산술	Reed-Solomon 오류 정정

전체 PHPDoc 표를 보려면 composer docs:generate-api-php -- --module=Barcode 를 실행하십시오.

코드 샘플 — 빠른 시작

소스: 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');

코드 샘플 — 프로덕션

레지스트리를 통해 2D 인코더를 직접 해석하되, 인코딩하기 전에 페이로드를 제한하십시오.

<?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는 검사 숫자를 계산하여 추가합니다. 미리 추가하지 마십시오.
2D $options 배열은 심볼로지별로 다릅니다(예: QR의 오류 정정 수준). 알 수 없는 키는 대부분의 인코더에서 무시됩니다. 인코더 자체 문서를 기준으로 키를 검증하십시오.
Barcode2DType은 core 에디션에서 인코더를 제공하는 범위보다 더 많은 심볼로지를 열거합니다. BarcodeEncoderRegistry::resolve()는 등록되지 않은 심볼로지에 대해 자리표시자를 반환하지 않고 예외를 발생시킵니다.
등록된 인코더는 공유 인스턴스입니다. 생성자 구성 이외에는 상태를 갖지 않게 유지하십시오. 호출별 상태는 동시 렌더링을 손상시킵니다.
지나치게 긴 페이로드는 더 조밀하고 큰 행렬을 생성합니다. 심볼 크기를 통한 서비스 거부를 방지하려면 인코딩하기 전에 페이로드 길이를 제한하십시오.

성능

인코딩 비용은 O(1)인 레지스트리 조회가 아니라 페이로드 길이와 행렬 크기에 따라 증가합니다. 짧은 Code 128 페이로드는 마이크로초 단위로 인코딩됩니다. 높은 오류 정정을 적용한 조밀한 QR Code가 가장 무거운 경우입니다. 다중 심볼 예제 페이지의 경우 1500 ms 벽시계 / 64 MB 피크 예산 내에 머무릅니다. 재현성 프로필은 bitwise입니다. 동일한 페이로드와 옵션은 항상 동일한 모듈 행렬과 동일한 그려진 바이트를 생성합니다.

보안 참고사항

바코드 페이로드는 종종 공격자의 영향을 받습니다 — 스캔된 URL, 일련번호, 추적 코드 등. 인코더는 바이트를 인코딩하며, 이를 해석하지는 않습니다. 악의적인 URL을 인코딩한 QR Code도 유효한 QR Code이므로, 페이로드 신뢰 여부는 소비자의 책임입니다. 행렬 크기 — 그리고 그에 따른 작업량과 출력 크기 —를 예산 내로 유지하려면 인코딩하기 전에 페이로드 길이를 제한하십시오. 다른 곳에서 바코드로부터 디코딩된 데이터가 애플리케이션에 다시 들어올 때는 신뢰할 수 없는 입력으로 취급하십시오. 엔진 위협 모델은 /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).
Graphics 모듈 — 인코딩된 행렬을 그리는 드로잉 계층.
Document 모듈 — 상위 수준의 write1DBarcode() / write2DBarcode() 파사드.
적합성 개요
엔진 보안 모델