Construire des extensions

L'architecture de TCPDF-Next est ouverte par conception. Les six extensions officielles (Artisan, Pro, Laravel, Symfony, CodeIgniter, Adaptation) utilisent les mêmes interfaces et points d'accroche disponibles pour tout développeur tiers.

Contrats d'interface

Votre extension devrait implémenter une ou plusieurs de ces interfaces :

PdfDocumentInterface

Le contrat de document principal. Implémentez ceci si vous construisez un moteur de document alternatif.

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

Implémentez ceci pour backends de signature personnalisés (HSM cloud, services de signature distants, etc.).

namespace Yeeefang\TcpdfNext\Contracts;

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

HsmSignerInterface

Pour intégration de module de sécurité matériel :

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

Pour stratégies de chargement de polices personnalisées :

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;
}

Squelette d'extension

Voici une extension tierce minimale :

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/"
        }
    }
}

Classe d'extension

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();
    }
}

Comment les extensions officielles se connectent

Fonctionnel

Artisan → Core

Le moteur de rendu Chrome est injecté via setChromeRendererConfig() sur la classe Document. Core stocke le moteur de rendu comme ?object — pas de dépendance de type sur Artisan.

Pro → Core

Les classes Pro comme LtvManager et PdfAManager opèrent sur BinaryBuffer et ObjectRegistry — les mêmes API internes que Core utilise. Le PadesOrchestrator accepte des paramètres optionnels Pro uniquement (CertificateChainValidator, OcspResponseVerifier).

Intégration framework

Laravel → Core

Le ServiceProvider crée un binding factory pour PdfDocumentInterface qui retourne une instance Document configurée. La Facade proxyfie les appels statiques vers l'instance résolue du conteneur.

Symfony → Core

Le TcpdfNextBundle enregistre PdfFactory comme service. Injectez-le via injection de constructeur ou l'attribut #[Autowire]. L'intégration Messenger dispatch GeneratePdfMessage pour génération asynchrone.

CodeIgniter → Core

Le TcpdfNextService s'enregistre dans le conteneur de services de CodeIgniter. Utilisez service('tcpdfnext') ou injectez via PdfLibrary dans les contrôleurs. L'intégration queue utilise le planificateur de tâches de CodeIgniter.

Compatibilité

Adaptation → Core

La classe adapter TCPDF étend une base non finale, mappant toutes les 252 méthodes legacy vers les équivalents TCPDF-Next. Les surcharges Header() et Footer() fonctionnent tel quel. Les classes helper legacy (TCPDF_STATIC, TCPDF_FONTS, TCPDF_COLORS, TCPDF_IMAGES) délèguent à l'API moderne.

Conventions d'espace de noms

Suivez le modèle de l'écosystème :

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

Utilisez les interfaces Yeeefang\TcpdfNext\Contracts\, jamais les classes internes Core\, pour vos frontières d'API publique.