Kiến trúc chi tiết

TCPDF-Next được tổ chức thành 26 module trên 4 package, với tổng cộng 213 file PHP.

Tổng quan kiến trúc

graph TB
    subgraph Core["Core (yeeefang/tcpdf-next)"]
        Doc[Document] --> Font[FontRegistry]
        Doc --> Img[ImageRegistry]
        Doc --> Sec[SecurityEngine]
        Doc --> Bar[BarcodeEngine]
    end
    subgraph Extensions["Extension"]
        Art["Artisan<br/>Chrome CDP"] -->|HTML→PDF| Doc
        Pro["Pro<br/>PAdES B-LTA"] -->|Signing| Sec
    end
    subgraph Frameworks["Framework"]
        Lara["Laravel 12"] -->|Facade| Doc
        Sym["Symfony 7"] -->|Bundle| Doc
        CI["CodeIgniter 4"] -->|Service| Doc
    end
    Adapt["Adaptation<br/>Legacy API"] -.->|Compat Layer| Doc

Thống kê dự án

Chỉ số	Core	Laravel	Artisan	Pro	Tổng
File PHP	148	4	17	47	213
Module	16	1	2	7	26
Test	908	--	7 class	--	908+
Assertion	28,881	--	--	--	28,881+
PHPStan level	10	10	10	10	10

Namespace Map

Core (yeeefang/tcpdf-next)

Yeeefang\TcpdfNext\
├── Core\               # Document, ObjectRegistry, TransactionManager, CrossReferenceStream
│   └── Concerns\       # 12 trait composable (HasMetadata, HasPages, ...)
├── Contracts\          # PdfDocumentInterface, SignerInterface, HsmSignerInterface, enum
├── ValueObjects\       # PageSize, Dimension, Margin, Position, Unit
├── Support\            # BinaryBuffer
├── Content\            # TextRenderer, JavaScriptManager, Hyphenator
│   └── Hyphenation\    # HyphenationPatterns
├── Typography\         # FontManager, TrueTypeParser, Type1Parser, FontSubsetter, BiDiResolver
├── Graphics\           # DrawingEngine, TransformEngine, Color, ImageLoader, SvgParser
├── Layout\             # HeaderFooter, ColumnLayout, BookletLayout, PageManager
├── Html\               # HtmlParser, TableParser, CssRule
├── Form\               # FormFieldManager, FormFlattener
├── Barcode\            # Barcode1D, Barcode2D, BarcodeRenderer
│   ├── QrCode\         # QrEncoder
│   ├── DataMatrix\     # DataMatrixEncoder
│   └── Pdf417\         # Pdf417Encoder
├── Navigation\         # BookmarkManager, LinkManager, TocBuilder, AnnotationManager
├── Accessibility\      # StructureTree, RoleMap, StructureElement
├── Security\           # Mã hóa + Chữ ký
│   ├── Encryption\     # Aes256Encryptor, SaslPrep
│   ├── Signature\      # DigitalSigner, PadesOrchestrator, CertificateInfo, SignatureAppearance
│   └── Timestamp\      # TsaClient
└── Writer\             # PdfWriter, Linearizer, ViewerPreferences, data class

Artisan (yeeefang/tcpdf-next-artisan)

Yeeefang\TcpdfNext\
├── Artisan\            # ChromeHtmlRenderer, BrowserPool, ChromeRendererConfig
│   └── Exception\      # ChromeNotAvailableException, ChromeRenderException, PdfParseException
└── Parser\             # PdfTokenizer, CrossRefParser, PdfReader, StreamDecoder, ResourceCollector

Laravel (yeeefang/tcpdf-next-laravel)

Yeeefang\TcpdfNext\Laravel\
├── TcpdfServiceProvider
├── Facades\Pdf
├── Http\PdfResponse
└── Jobs\GeneratePdfJob

Pro (yeeefang/tcpdf-next-pro)

Yeeefang\TcpdfNext\
├── Archive\            # PdfAManager, PdfAVersion, XmpMetadata, OutputIntent
├── Barcode\            # Barcode chuyên biệt
│   ├── MicroQr\        # MicroQrEncoder
│   ├── DotCode\        # DotCodeEncoder
│   ├── HanXin\         # HanXinEncoder
│   ├── JabCode\        # JabCodeEncoder (LDPC, interleaver, matrix)
│   ├── Gs1\            # Gs1DataParser
│   └── Imb\            # ImbEncoder
├── Security\
│   ├── Ltv\            # LtvManager, DssBuilder, OcspClient, CrlFetcher, CertificateChainValidator
│   ├── Signature\Hsm\  # Pkcs11Signer, OpenSslEngineSigner
│   ├── Timestamp\      # DocumentTimestamp
│   ├── Asn1\           # CertificateParser, AlgorithmIdentifier
│   └── CertificateTransparency\  # CtValidationResult
└── Writer\             # IncrementalUpdateWriter

Lazy Initialization

Class Document chỉ khởi tạo sub-engine thiết yếu trong constructor:

Luôn khởi tạo: DocumentData, PdfWriter, FontManager, DrawingEngine, TransformEngine, TextRenderer, HeaderFooter, ColumnLayout, BookmarkManager, LinkManager, TocBuilder, AnnotationManager, PageManager, FontMetrics

Lazy (null cho đến khi dùng lần đầu): FormFieldManager, LayerManager, TemplateManager, TransactionManager, BookletLayout, FileAttachment, JavaScriptManager, SvgParser, EpsParser, StructureTree, SpotColorManager, ImageLoader, BiDiResolver

Điều này giữ footprint bộ nhớ cơ bản nhỏ cho document đơn giản trong khi cung cấp đầy đủ chức năng khi cần.

Tích hợp Extension

Core package phát hiện extension lúc runtime qua class_exists():

// Phát hiện Artisan
$rendererClass = 'Yeeefang\\TcpdfNext\\Artisan\\ChromeHtmlRenderer';
if (!class_exists($rendererClass)) {
    throw new \RuntimeException(
        'Chrome renderer requires yeeefang/tcpdf-next-artisan.'
    );
}

Điều này nghĩa là:

• Core có không dependency cứng vào Artisan, Laravel, hoặc Pro
• Extension được autoload bởi Composer — chỉ cần composer require và chúng hoạt động
• Laravel ServiceProvider tự phát hiện Artisan và Pro, cấu hình binding tương ứng