Référence Interfaces
Le module Contracts (TcpdfNext\Contracts) définit les interfaces partagées contre lesquelles tous les modules TCPDF-Next programment. En dépendant de contrats plutôt que de classes concrètes, vous pouvez substituer des doublures de test, créer des implémentations alternatives et maintenir une API publique stable entre versions majeures.
PdfDocumentInterface
Namespace: TcpdfNext\Contracts\PdfDocumentInterface
Le contrat API principal implémenté par Document. Toute classe remplissant cette interface peut être utilisée comme remplacement direct pour le modèle de document intégré.
Méthodes
pageSize(PageSize $size): static
Définir la taille de page par défaut pour les nouvelles pages.
orientation(Orientation $orientation): static
Définir l'orientation de page par défaut.
margin(Margin $margin): static
Définir les marges de page par défaut.
metadata(?string $title = null, ?string $author = null, ?string $subject = null, ?string $keywords = null, ?string $creator = null): static
Définir les métadonnées au niveau document. Tous les paramètres sont optionnels ; passer seulement ceux que vous voulez définir.
addPage(?PageSize $pageSize = null, ?Orientation $orientation = null): static
Ajouter une nouvelle page, optionnellement surcharger les valeurs par défaut pour cette page.
font(string $family, float $size = 12.0, string $style = ''): static
Sélectionner une police par nom de famille, taille et style.
text(string $content): static
Écrire une ligne de texte à la position courante du curseur.
output(OutputDestination $destination = OutputDestination::String, ?string $filename = null, ?string $path = null): string|bool
Rendre le PDF vers la destination choisie.
currentPage(): int
Retourner le numéro de page actuelle (1-based).
pageCount(): int
Retourner le nombre total de pages.
Exemple
php
use TcpdfNext\Contracts\PdfDocumentInterface;
use TcpdfNext\Contracts\OutputDestination;
function generateReport(PdfDocumentInterface $pdf): string
{
return $pdf
->addPage()
->font('Helvetica', size: 14)
->text('Rapport trimestriel')
->output(OutputDestination::String);
}FontManagerInterface
Namespace: TcpdfNext\Contracts\FontManagerInterface
Définit le chargement de polices, l'enregistrement, le subsetting et la recherche de métriques. Le FontManager intégré implémente cette interface, mais vous pouvez fournir une implémentation personnalisée pour des sources de polices spécialisées.
Méthodes
registerFont(string $path, string $alias = ''): static
Enregistrer un fichier de police TrueType ou OpenType. Si alias est vide, le nom de famille depuis le fichier est utilisé.
hasFont(string $family, string $style = ''): bool
Vérifier si une combinaison famille et style de police est disponible.
getFont(string $family, string $style = ''): FontInfo
Retourner un objet FontInfo readonly avec métriques pour la police spécifiée.
stringWidth(string $text, string $family, float $size, string $style = ''): float
Calculer la largeur d'une chaîne en unités utilisateur.
subset(string $family, string $style, string $chars): string
Créer un binaire de police subset contenant uniquement les glyphes nécessaires pour les caractères donnés.
registeredFamilies(): array
Retourner une liste de tous les noms de famille de polices enregistrées.
Exemple
php
use TcpdfNext\Contracts\FontManagerInterface;
function addCustomFonts(FontManagerInterface $fonts): void
{
$fonts->registerFont('/fonts/NotoSans-Regular.ttf', 'NotoSans');
$fonts->registerFont('/fonts/NotoSans-Bold.ttf', 'NotoSans');
if ($fonts->hasFont('NotoSans', 'B')) {
$info = $fonts->getFont('NotoSans', 'B');
echo "Ascender: {$info->ascender}";
}
}SignerInterface
Namespace: TcpdfNext\Contracts\SignerInterface
Définit le contrat pour tout fournisseur de signature numérique. Implémentez cette interface pour intégrer avec certificats logiciels, coffres-forts de clés cloud ou modules de sécurité matérielle (HSM).
Méthodes
sign(string $data): string
Signer les données données et retourner les octets de signature CMS/CAdES bruts.
certificate(): string
Retourner le certificat de signature encodé DER.
chain(): array
Retourner un tableau de certificats intermédiaires encodés DER (du signataire à la racine).
estimatedSize(): int
Retourner la taille maximale estimée (en octets) de la signature. Utilisé pour pré-allouer le placeholder ByteRange.
algorithm(): string
Retourner l'OID ou nom de l'algorithme de signature (ex., 'sha256WithRSAEncryption').
Exemple
php
use TcpdfNext\Contracts\SignerInterface;
class FileSigner implements SignerInterface
{
public function __construct(
private readonly string $certPath,
private readonly string $keyPath,
private readonly string $password,
) {}
public function sign(string $data): string
{
$cert = file_get_contents($this->certPath);
$key = openssl_pkey_get_private(
file_get_contents($this->keyPath),
$this->password,
);
openssl_pkcs7_sign(/* ... */);
// Retourner octets de signature bruts
}
public function certificate(): string { /* ... */ }
public function chain(): array { return []; }
public function estimatedSize(): int { return 8192; }
public function algorithm(): string { return 'sha256WithRSAEncryption'; }
}HsmSignerInterface
Namespace: TcpdfNext\Contracts\HsmSignerInterface
Étend SignerInterface pour les modules de sécurité matérielle qui n'exposent jamais la clé privée. Au lieu de signer des données brutes, le HSM signe un condensé pré-calculé.
Méthodes
Toutes les méthodes de SignerInterface, plus :
signDigest(string $digest, string $algorithm): string
Signer un condensé de message pré-calculé. Le paramètre algorithm identifie le hash utilisé (ex., 'sha256').
Exemple
php
use TcpdfNext\Contracts\HsmSignerInterface;
class AwsCloudHsmSigner implements HsmSignerInterface
{
public function __construct(
private readonly string $keyId,
private readonly AwsKmsClient $kms,
private readonly string $certPem,
) {}
public function sign(string $data): string
{
$digest = hash('sha256', $data, binary: true);
return $this->signDigest($digest, 'sha256');
}
public function signDigest(string $digest, string $algorithm): string
{
$result = $this->kms->sign([
'KeyId' => $this->keyId,
'Message' => $digest,
'MessageType' => 'DIGEST',
'SigningAlgorithm' => 'RSASSA_PKCS1_V1_5_SHA_256',
]);
return $result['Signature'];
}
public function certificate(): string { return $this->certPem; }
public function chain(): array { return []; }
public function estimatedSize(): int { return 16384; }
public function algorithm(): string { return 'sha256WithRSAEncryption'; }
}Utiliser les interfaces pour les tests
Les quatre interfaces sont conçues pour être facilement mockables avec PHPUnit ou Mockery.
php
use PHPUnit\Framework\TestCase;
use TcpdfNext\Contracts\FontManagerInterface;
class TextRendererTest extends TestCase
{
public function testCalculatesWidth(): void
{
$fonts = $this->createMock(FontManagerInterface::class);
$fonts->method('hasFont')->willReturn(true);
$fonts->method('stringWidth')
->with('Hello', 'Helvetica', 12.0, '')
->willReturn(26.64);
$renderer = new TextRenderer($fonts);
$this->assertEqualsWithDelta(26.64, $renderer->width('Hello'), 0.01);
}
}Voir aussi
- Vue d'ensemble API -- Tous les packages en un coup d'œil
- Référence Enums -- Enums utilisés par ces interfaces (Orientation, Alignment, OutputDestination)
- API Document -- La classe concrète qui implémente PdfDocumentInterface
- Guide sécurité -- Guide complet du chiffrement et signatures numériques