PDF에 1D 및 2D 바코드 생성

한눈에 보기

이 레시피는 1D 및 2D 바코드를 PDF 페이지에 직접 그립니다. Core HasBarcodes 트레이트는 write1DBarcode()와 write2DBarcode()를 제공합니다. 두 메서드 모두 현재 페이지에 네이티브 PDF 경로 연산자로 심볼을 그리므로, 출력은 단순하고 결정론적인 벡터 콘텐츠입니다. 이 레시피는 examples/10-barcodes.php를 따릅니다.

설치

composer require nextpdf/core:^3

추가 확장 모듈은 필요하지 않습니다. 바코드 인코더는 순수 PHP이며, 심볼은 표준 PDF 사각형 연산자(ISO 32000-2 §8.5)로 그려집니다.

개념 개요

바코드는 이미지로 임베드되는 것이 아니라 직접 그려집니다. 페이로드는 제품 번호나 웹 주소처럼 인코딩할 데이터입니다.

write1DBarcode()는 선택한 BarcodeType에 맞춰 페이로드를 bar/space 패턴으로 인코딩한 다음, 채워진 사각형 시퀀스를 내보냅니다. 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은 1D 심볼로지(C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …)를 나열하고, Barcode2DType은 2D 심볼로지(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를 그대로 반영합니다. 이 예제는 하니스가 NEXTPDF_COOKBOOK_OUTPUT를 통해 제공하는 경로에 PDF를 쓰고, 수동으로 실행할 때는 로컬 파일로 대체합니다. 그러면 재현성 하니스가 이를 두 번 실행하여 구조적 동일성을 검증할 수 있습니다. 구조는 저장 시마다 달라지는 /ID 및 타임스탬프 아톰을 제거한 상태로 qpdf로 정규화됩니다.

<?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자리 숫자를 요구합니다. 유효하지 않은 페이로드는 콘텐츠가 쓰이기 전에 예외를 발생시킵니다. UPCA, ISBN, ISSN은 각각 고유한 길이 및 검사 숫자 규칙을 가집니다.
x/y는 선택 사항입니다. 이를 생략하면 바코드가 현재 커서 위치에 배치됩니다. 예측 가능한 레이아웃을 위해 명시적인 좌표를 전달하십시오.
w = 0은 자동으로 크기를 조정합니다. 너비를 0으로 지정하면 인코더가 자연스러운 모듈 너비를 선택합니다. 고정된 박스에 맞추려면 양수 너비를 전달하십시오.
2D 오류 정정 레벨. write2DBarcode()는 가장 낮은 레벨인 ecLevel: 'L'을 기본값으로 사용합니다. 인쇄 손상에도 견뎌야 하는 QR Code의 경우 레벨을 높이십시오('M', 'Q', 'H'). 레벨이 높을수록 매트릭스가 커집니다.
GS1 애플리케이션 식별자. FNC1 접두사가 있는 GS1 구조화 데이터에는 gs1: true를 write2DBarcode()에 전달하거나 BarcodeType::GS1_128을 사용하십시오.
페이지가 암시적으로 생성됩니다. addPage() 이전에 바코드 메서드를 호출하면 NextPDF가 먼저 페이지를 추가합니다. 이는 편리하지만 페이지 지오메트리가 중요한 경우에는 addPage()를 명시적으로 호출하십시오.

성능

인코딩은 1D의 경우 O(페이로드 길이), 2D의 경우 O(매트릭스 면적)이며, 둘 다 마이크로초 단위로 완료됩니다. 각 모듈은 하나의 re … f 경로 연산자이므로, 밀도가 높은 QR Code는 콘텐츠 스트림에 몇 킬로바이트를 추가합니다. 래스터화 단계가 없으므로 심볼 크기와 관계없이 메모리는 일정하게 유지됩니다. 이 레시피는 1500 ms / 64 MB 예산을 충분히 충족합니다.

보안 참고 사항

바코드는 전달하는 모든 페이로드를 담으므로, 소비 측에서는 바코드 값을 다른 신뢰할 수 없는 입력과 동일하게 취급하십시오. 이 라이브러리는 페이로드에 서명하거나 인증하지 않습니다. 2D 심볼은 암호화가 아닙니다. 스캐너를 가진 사람은 누구나 읽을 수 있습니다.

적합성

명제	사양	절
바코드 모듈은 사각형 경로 구성 연산자로 그려집니다.	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로 제한됩니다. 인용은 절 ID와 reference_id 포인터뿐이며, 표준 텍스트는 재현되지 않습니다.