하나의 엔진, 모든 프레임워크

Spec: PSR-11 Container, §1.1.2Spec: PSR-4 Autoloader, §3

한눈에 보기

성장하는 PHP 환경은 대부분 결국 둘 이상의 프레임워크를 갖게 됩니다. NextPDF 는 그 각각을 그 나름의 방식으로 만나는 하나의 PDF 엔진입니다: Laravel, Symfony, CodeIgniter 를 위한 관용적 브리지와, 그 어느 것에서도 실행되지 않는 코드를 위한 독립 실행 경로입니다. 문서 모델은 공유됩니다. 그것을 호출하는 방식만 달라집니다.

이것이 중요한 이유

스택마다 다른 PDF 라이브러리를 두는 것은 조용한 세금입니다. 각각은 저마다의 특이점, 저마다의 폰트 처리, 유효함이 무엇인지에 대한 저마다의 생각을 갖고 있습니다. Laravel 서비스에서 올바르게 렌더링되는 송장이 Symfony 워커에서는 미묘하게 다르게 렌더링될 수 있습니다. 다른 라이브러리가 그것을 그렸기 때문입니다. 이제 여러분의 아카이브 대상, 서명 배치, 접근성 태그가 어느 팀이 그 문서를 출하했는지에 따라 달라집니다. 버그 리포트는 “PDF 가 잘못됐다”고 말하고, 그 답은 세 엔진 중 어느 것이 그것을 생성했는지에 달려 있습니다.

하나의 엔진으로 표준화하면 그 표면이 줄어듭니다. PDF/A 프로파일이 결정되는 단일 지점, 인증할 하나의 폰트 파이프라인, 신뢰할 하나의 검증기가 있습니다. 여러분이 마침 어느 프레임워크 안에 있느냐가 문서가 올바른지를 좌우하는 변수가 되지 않게 됩니다.

짧은 요약

코어 엔진은 프레임워크 비종속입니다. nextpdf/core 는 HTTP, 라우팅, 컨테이너 배선에 대해 아무것도 모릅니다. 그것은 PDF 2.0 엔진이며 그 이상은 아닙니다.
각 브리지는 적응할 뿐, 재구현하지 않습니다. Laravel, Symfony, CodeIgniter 패키지는 파사드 또는 팩토리, HTTP 응답 헬퍼, 그리고 큐 또는 비동기 생성 경로를 제공합니다 — 동일한 엔진 위에서 말입니다.
브리지는 여러분의 문서가 아니라 여러분의 프레임워크를 따릅니다. 그것은 엔진을 호출하는 방식을 바꿀 뿐, 엔진이 생성할 수 있는 것은 결코 바꾸지 않습니다.
독립 실행은 언제나 사용할 수 있습니다. CLI 도구, 데몬, 또는 라이브러리에는 브리지를 걸 프레임워크가 없습니다; 그것은 문서를 직접 구성합니다.
하나의 문서 모델이 네 가지 모두를 가로질러 이동합니다. 동일한 값 객체, 열거형, 출력 계약이 어디에나 나타나므로, 문서는 호출 지점 사이를 바뀌지 않은 채 이동합니다.

NextPDF 의 접근 방식

이 아키텍처는 의도적인 분할입니다. 엔진은 자산이며; 브리지는 한 프레임워크의 관용을 말하는 얇은 어댑터입니다. 브리지는 표준 오토로딩 (Spec: PSR-4 Autoloader, §3)을 통해 공유된 코어 위에 작은 네임스페이스를 등록하고, 컨테이너 계약 (Spec: PSR-11 Container, §1.1.2)을 통해 문서를 돌려줍니다. 그 계약이 여기서 조용한 주인공입니다: 그것은 동일한 식별자에 대한 두 번의 해석이 서로 다른 인스턴스를 반환하도록 허용하며, 바로 그것이 브리지가 파싱된 폰트 레지스트리와 이미지 캐시는 프로세스 전역 싱글톤으로 유지하면서도 요청마다 신선하고 일회용인 문서를 여러분에게 제공하는 방식입니다. 오래 사는 워커들 — Octane, RoadRunner, Swoole, Messenger — 은 요청 간 상태 누출 없이, 구조적으로, 분할 상환된 폰트 파싱을 얻습니다.

네 가지 관용은 표면에서만 다릅니다:

Core enginenextpdf/core — the framework-agnostic PDF 2.0 engine; the single shared document model, value objects, and output contract.
Laravel bridgenextpdf/laravel — auto-discovered provider, a Pdf facade, a PdfResponse helper, and a queued GeneratePdfJob.
Symfony bridgenextpdf/symfony — an auto-registered bundle, an injectable PdfFactory, a PdfResponse, and an optional Messenger handler.
CodeIgniter bridgenextpdf/codeigniter — a service and pdf() helper, a Pdf library over a disposable Document, and a PdfResponse.
StandaloneNo framework to bridge from — construct a Document directly in a CLI tool, daemon, or library.

One framework-agnostic core engine reached through four idiomatic surfaces: a Laravel facade, an injected Symfony factory, a CodeIgniter service, or a directly constructed standalone document — each handing back the same disposable Document model.

다이어그램을 왼쪽에서 오른쪽으로 읽으면 그 교훈은 대칭성입니다. 모든 표면이 동일한 Document 로 해석됩니다. Laravel 파사드, Symfony 팩토리, CodeIgniter 서비스, 그리고 독립 실행 생성자는 하나의 방으로 들어가는 네 개의 문입니다.

실전 예제

동일한 세 줄의 의도를, 각 관용으로 표현한 것입니다. 문서를 구성하는 본문 — 페이지, 폰트, 셀, 서명, 적합성 — 은 네 가지 모두에서 동일합니다. 같은 엔진이기 때문입니다.

<?php

declare(strict_types=1);

// Laravel — resolve a fresh document from the container.
use NextPDF\Contracts\PdfDocumentInterface;
$document = app(PdfDocumentInterface::class);

// Symfony — inject the factory, then ask it for a document.
use NextPDF\Symfony\Service\PdfFactory;
$document = $factory->create(); // PdfFactory injected into your service

// CodeIgniter — pull it from the Services layer.
use NextPDF\CodeIgniter\Config\Services;
$document = Services::pdfDocument();

// Standalone — no framework; construct it directly.
use NextPDF\Core\Document;
$document = Document::createStandalone();

// From here, the code is identical regardless of how $document arrived.
$document->addPage();
$document->cell(0, 10, 'One engine, every framework', newLine: true);
$bytes = $document->getPdfData();

첫 줄들만이 유일한 차이입니다. 그 이후의 모든 것은 이식 가능합니다: 문서 구성 서비스를 Symfony 에서 독립 실행 워커로 옮겨도 렌더링 코드는 바뀌지 않습니다. 그것이 의존하는 계약이 바뀌지 않았기 때문입니다.

흔한 오해

흔한 가정은 프레임워크 브리지가 기능을 잠금 해제한다는 것입니다 — 엔진을 직접 호출하는 대신 nextpdf/laravel 을 설치했기 때문에 장기 서명 검증이나 구조화된 전자 송장이 도착한다는 것입니다. 그렇지 않습니다. 브리지는 호출 지점을 바꿀 뿐, 엔진의 범위는 결코 바꾸지 않습니다. PDF/A 출력과 PAdES 기준선 서명 같은 코어 기능은 오픈 소스이며 모든 표면에 도달합니다; 고급 기능은 에디션으로 잠금 해제되며, 그러고 나면 어떤 브리지를 통해서든 독립 실행 경로를 통해서든 똑같이 사용할 수 있게 됩니다. 프레임워크 통합을 선택하는 것은 기능 집합을 선택하는 것이 아닙니다.

거울 같은 오해는 “하나의 엔진”이 모든 문서에 대해 하나의 렌더링 경로를 의미해야 한다는 것입니다. 그렇지 않습니다. 인-프로세스 엔진은 PDF 를 직접 렌더링합니다; 문서가 진정으로 브라우저급 레이아웃 엔진을 필요로 할 때는 렌더러 패키지가 그것을 처리합니다. 렌더링과 호출은 별개의 축입니다 — integration decision guide가 그것을 매핑하는 곳입니다.

한계와 경계

브리지는 엔진이 렌더링할 수 있는 것을 확장하지 않습니다. 그것이 정직한 한계이며, 바로 그것이 핵심입니다: 역량은 코어와 등급에 있지, 여러분이 그것에 도달하는 어댑터에 있지 않습니다.

Framework bridges over one engine — edition availability
Edition	Availability
Core	모든 브리지(Laravel, Symfony, CodeIgniter)와 독립 실행 경로는 Apache-2.0 이며 Core 에 대해 동작합니다. 그것들은 엔진을 적응시키거나 노출하며; 기능을 게이트하지 않고 엔진이 생성할 수 있는 것을 바꾸지 않습니다.
Pro	장기 서명 검증(PAdES B-LT 와 B-LTA) 같은 고급 기능은 에디션으로 잠금 해제되며, 그러고 나면 어떤 브리지를 통해서든 독립 실행을 통해서든 동일하게 도달합니다 — 프레임워크를 바꿈으로써가 결코 아닙니다. PDF/A 보존용 출력과 PAdES 기준선 서명 (B-B 와 B-T)은 이미 Core 에 있으며, 모든 표면을 통해 동일한 방식으로 사용할 수 있습니다.
Enterprise	구조화된 전자 송장(EN 16931)과 더 깊은 적합성 도구도 에디션 기능이며, 마찬가지로 어느 표면이 엔진을 호출하든 동일하고, 적합성 검증 자체는 Core 에 탑재되어 있습니다.

두 가지 추가 경계를 분명히 말해 둘 가치가 있습니다. 첫째, 각 브리지는 자기 프레임워크의 현재 메이저를 추적합니다 — Laravel, Symfony, CodeIgniter 는 각각 지원되는 범위를 고정하므로 “모든 프레임워크”는 모든 역사적 릴리스가 아니라 각각의 지원 버전을 의미합니다; 각 패키지의 자체 문서를 그 API 의 권위 있는 출처로 취급하십시오. 둘째, 브리지는 프레임워크 어댑터이지 렌더링 백엔드가 아닙니다. 문서가 완전한 브라우저 레이아웃 엔진을 필요로 한다면, 그것은 어느 프레임워크가 엔진을 호출했는지와 무관한 렌더러 선택입니다.

용어집

코어 엔진(Core engine) — nextpdf/core, 모든 브리지와 독립 실행 경로가 그 위에 구축하는 프레임워크 비종속 PDF 2.0 엔진.
프레임워크 브리지(Framework bridge) — 엔진을 한 프레임워크의 관용 — 파사드, 팩토리, 응답, 큐 작업 — 에 적응시키되 그 기능은 바꾸지 않는 통합 패키지(Laravel, Symfony, CodeIgniter).
독립 실행 경로(Standalone path) — 프레임워크 없이 Document 를 직접 구성하여 코어 엔진을 그대로 사용하는 것; CLI 도구, 데몬, 라이브러리를 위한 경로.
일회용 문서(Disposable document) — 한 번 쓰는 Document 계약: 구성하고, 내보내고, 버립니다. 각 컨테이너 해석은 신선한 것을 반환하므로, 오래 사는 워커에서 요청 간에 상태가 누출되지 않습니다.
PAdES — PDF Advanced Electronic Signatures, PDF 서명을 위한 ETSI 프로파일 제품군. 기준선 서명(B-B 와 B-T)은 Core 에 있고; 장기 검증(B-LT 와 B-LTA)은 고급 에디션 기능입니다. 둘 중 어느 것이든 어떤 표면을 통해서든 도달하며, 서명 페이지들에서 깊이 다룹니다.