Construir extensiones

La arquitectura de TCPDF-Next es abierta por diseño. Las seis extensiones oficiales (Artisan, Pro, Laravel, Symfony, CodeIgniter, Adaptation) usan las mismas interfaces y puntos de enganche disponibles para cualquier desarrollador de terceros.

Contratos de interfaz

Tu extensión debería implementar una o más de estas interfaces:

PdfDocumentInterface

El contrato central del documento. Impleméntalo si estás construyendo un motor de documentos alternativo.

namespace Yeeefang\TcpdfNext\Contracts;

interface PdfDocumentInterface
{
    public function addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait): static;
    public function setMargins(Margin $margin): static;
    public function setFont(string $family, string $style = '', float $size = 12.0): static;
    public function cell(float $width, float $height, string $text = '', ...): static;
    public function multiCell(float $width, float $height, string $text, ...): static;
    public function writeHtml(string $html): static;
    public function image(string $file, ...): static;
    public function output(?string $filename = null, OutputDestination $dest = OutputDestination::Inline): string;
    public function save(string $path): void;
}

SignerInterface

Impleméntalo para backends de firma personalizados (HSMs en la nube, servicios de firma remota, etc.).

namespace Yeeefang\TcpdfNext\Contracts;

interface SignerInterface
{
    public function sign(string $data): SignatureResult;
    public function timestamp(string $signatureValue): string;
    public function supportsLtv(): bool;
}

HsmSignerInterface

Para integración con módulos de seguridad hardware:

namespace Yeeefang\TcpdfNext\Contracts;

interface HsmSignerInterface
{
    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string;
    public function getCertificateDer(): string;
    public function getCertificateChainDer(): array;
    public function getPublicKeyAlgorithm(): string;
}

FontManagerInterface

Para estrategias personalizadas de carga de fuentes:

namespace Yeeefang\TcpdfNext\Contracts;

interface FontManagerInterface
{
    public function registerFont(string $fontFile, string $alias = '', int $fontIndex = 0): FontInfo;
    public function getFont(string $family, string $style = ''): ?FontInfo;
    public function subset(FontInfo $font, string $text): string;
    public function getRegisteredFonts(): array;
    public function addFontDirectory(string $directory): void;
}

Esqueleto de extensión

Aquí hay una extensión de terceros mínima:

composer.json

{
    "name": "your-vendor/tcpdf-next-watermark",
    "description": "Advanced watermark extension for TCPDF-Next",
    "type": "library",
    "require": {
        "php": "^8.5",
        "yeeefang/tcpdf-next": "^1.7"
    },
    "autoload": {
        "psr-4": {
            "YourVendor\\TcpdfNextWatermark\\": "src/"
        }
    }
}

Clase de extensión

namespace YourVendor\TcpdfNextWatermark;

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Graphics\Color;

final class WatermarkExtension
{
    public function apply(
        Document $document,
        string $text,
        float $angle = 45.0,
        float $opacity = 0.15,
    ): Document {
        return $document
            ->startTransform()
            ->setAlpha($opacity)
            ->rotate($angle, $document->getPageWidth() / 2, $document->getPageHeight() / 2)
            ->setFontSize(60)
            ->setTextColor(200, 200, 200)
            ->text(
                $document->getPageWidth() / 4,
                $document->getPageHeight() / 2,
                $text,
            )
            ->stopTransform();
    }
}

Cómo se conectan las extensiones oficiales

Funcional

Artisan a Core

El renderizador Chrome se inyecta via setChromeRendererConfig() en la clase Document. Core almacena el renderizador como ?object — sin dependencia de tipo en Artisan.

Pro a Core

Las clases Pro como LtvManager y PdfAManager operan sobre BinaryBuffer y ObjectRegistry — las mismas APIs internas que usa Core. El PadesOrchestrator acepta parámetros opcionales exclusivos de Pro (CertificateChainValidator, OcspResponseVerifier).

Integración con frameworks

Laravel a Core

El ServiceProvider crea un binding factory para PdfDocumentInterface que retorna una instancia configurada de Document. El Facade proxifica llamadas estáticas a la instancia resuelta del contenedor.

Symfony a Core

El TcpdfNextBundle registra PdfFactory como servicio. Inyéctalo via inyección de constructor o el atributo #[Autowire]. La integración con Messenger despacha GeneratePdfMessage para generación asíncrona.

CodeIgniter a Core

El TcpdfNextService se registra en el contenedor de servicios de CodeIgniter. Usa service('tcpdfnext') o inyecta via PdfLibrary en controladores. La integración con colas usa el task scheduler de CodeIgniter.

Compatibilidad

Adaptation a Core

La clase adaptadora TCPDF extiende una base no final, mapeando los 252 métodos legacy a equivalentes de TCPDF-Next. Las sobrescrituras de Header() y Footer() funcionan tal cual. Las clases helper legacy (TCPDF_STATIC, TCPDF_FONTS, TCPDF_COLORS, TCPDF_IMAGES) delegan a la API moderna.

Convenciones de namespace

Sigue el patrón del ecosistema:

YourVendor\TcpdfNext{ExtensionName}\
├── YourMainClass.php
├── Config\
├── Exception\
└── ...

Usa interfaces de Yeeefang\TcpdfNext\Contracts\, nunca clases internas de Core\, para los límites de tu API pública.