Configurazione

TCPDF-Next viene fornito con impostazioni predefinite sensate che funzionano immediatamente. Ogni impostazione può essere sovrascritta al momento della creazione del documento o successivamente tramite setter fluenti.

Impostazioni Predefinite Documento

Quando chiami Document::create(), si applicano le seguenti impostazioni predefinite a meno che tu non specifichi diversamente:

Impostazione	Predefinito	Descrizione
Dimensione pagina	PageSize::A4	ISO A4 (210 × 297 mm)
Orientamento	Orientation::Portrait	Modalità verticale
Unità	Unit::Millimeter	Tutte le misure in millimetri
Margine sinistro	15 mm	Margine sinistro pagina
Margine superiore	27 mm	Margine superiore pagina
Margine destro	15 mm	Margine destro pagina
Margine inferiore	25 mm	Margine inferiore pagina
Interruzione automatica pagina	true	Interruzione automatica pagina vicino al margine inferiore
Font	Helvetica, 12 pt	Famiglia e dimensione font predefinita

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Unit;

$doc = Document::create(
    pageSize: PageSize::Letter,
    orientation: Orientation::Landscape,
    unit: Unit::Inch,
);

Margini

I margini possono essere impostati globalmente o per pagina:

use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// Margini globali
$doc->setMargins(new Margin(
    left: 20,
    top: 30,
    right: 20,
    bottom: 25,
));

// Override per una pagina specifica
$doc->addPage(
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

Percorsi e Directory Font

TCPDF-Next cerca i file font in un insieme configurabile di directory. I font integrati (Helvetica, Courier, Times, Symbol, ZapfDingbats) sono sempre disponibili. Per font personalizzati o Unicode, registra percorsi aggiuntivi:

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    // Aggiungi una directory contenente file .ttf / .otf
    $config->addDirectory('/path/to/my/fonts');

    // Aggiungi un singolo file font con alias famiglia
    $config->addFont('/path/to/MyFont-Regular.ttf', alias: 'MyFont');
});

TIP

I file font vengono incorporati come subset per impostazione predefinita, mantenendo compatto l'output PDF. L'incorporamento completo può essere abilitato per font quando necessario.

Impostazioni Crittografia

La crittografia PDF è configurata tramite il value object EncryptionConfig:

use Yeeefang\TcpdfNext\Core\Config\EncryptionConfig;
use Yeeefang\TcpdfNext\Core\Enums\EncryptionLevel;
use Yeeefang\TcpdfNext\Core\Enums\Permission;

$doc->setEncryption(new EncryptionConfig(
    level: EncryptionLevel::AES256,
    userPassword: 'reader-pass',
    ownerPassword: 'admin-pass',
    permissions: [
        Permission::Print,
        Permission::Copy,
    ],
));

Livello	Descrizione
EncryptionLevel::RC4_40	RC4 40-bit legacy (non raccomandato)
EncryptionLevel::RC4_128	RC4 128-bit
EncryptionLevel::AES128	AES 128-bit
EncryptionLevel::AES256	AES 256-bit (raccomandato)

Impostazioni PDF Taggato

I PDF taggati (accessibili) migliorano il supporto screen-reader e sono richiesti da PDF/UA. Abilita il tagging globalmente:

$doc->enableTaggedPdf();

// Opzionalmente imposta la lingua del documento per accessibilità
$doc->setLanguage('en');

Quando la modalità PDF taggato è attiva, i tag strutturali (<P>, <H1>–<H6>, <Table>, ecc.) vengono emessi automaticamente dalle API di testo e tabelle.

Modalità Deterministica

Per impostazione predefinita, i PDF contengono timestamp e identificatori unici che rendono ogni output unico. La modalità deterministica li rimuove, producendo output byte-identico per lo stesso input — utile per snapshot testing e build riproducibili:

$doc->enableDeterministicMode();

WARNING

La modalità deterministica rimuove date di creazione/modifica e l'identificatore file unico. Non usarla per documenti che richiedono questi campi metadata.

Esempio Configurazione Completa

Di seguito uno snippet singolo che mostra insieme tutte le principali opzioni di configurazione:

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Unit;
use Yeeefang\TcpdfNext\Core\Enums\EncryptionLevel;
use Yeeefang\TcpdfNext\Core\Enums\Permission;
use Yeeefang\TcpdfNext\Core\Config\EncryptionConfig;
use Yeeefang\TcpdfNext\Core\Config\FontConfig;
use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

$doc = Document::create(
    pageSize: PageSize::A4,
    orientation: Orientation::Portrait,
    unit: Unit::Millimeter,
);

// Margini
$doc->setMargins(new Margin(
    left: 15,
    top: 27,
    right: 15,
    bottom: 25,
));

// Font
$doc->configureFonts(function (FontConfig $config): void {
    $config->addDirectory('/path/to/fonts');
});

// Crittografia
$doc->setEncryption(new EncryptionConfig(
    level: EncryptionLevel::AES256,
    userPassword: '',
    ownerPassword: 'secret',
    permissions: [Permission::Print],
));

// Accessibilità
$doc->enableTaggedPdf();
$doc->setLanguage('en');

// Output deterministico (per test)
// $doc->enableDeterministicMode();

// Metadata
$doc->setTitle('Company Report');
$doc->setAuthor('TCPDF-Next');
$doc->setSubject('Monthly Summary');
$doc->setKeywords('report, finance, 2026');

$doc->addPage();
$doc->cell(text: 'Hello, configured world!');
$doc->save('/tmp/configured.pdf');