Utilizzo Base

Questa pagina illustra i blocchi fondamentali di ogni documento TCPDF-Next: creazione documento, aggiunta pagine, scrittura testo, incorporamento immagini e produzione output.

Creazione Documento

Il factory statico Document::create() è il singolo punto di ingresso per ogni PDF:

use Yeeefang\TcpdfNext\Core\Document;

$doc = Document::create();

Tutti i parametri sono opzionali — le impostazioni predefinite forniscono un documento A4 verticale misurato in millimetri. Vedi la pagina Configurazione per l'elenco completo delle opzioni.

Aggiunta Pagine

Un documento inizia vuoto. Chiama addPage() almeno una volta prima di scrivere qualsiasi contenuto:

use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// Aggiungi una pagina con le impostazioni predefinite del documento
$doc->addPage();

// Aggiungi una pagina Letter orizzontale con margini personalizzati
$doc->addPage(
    pageSize: PageSize::Letter,
    orientation: Orientation::Landscape,
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

Dimensioni Pagina Disponibili

PageSize è un backed enum che include tutte le dimensioni standard ISO e Nord Americane:

Valore Enum	Dimensioni
PageSize::A3	297 × 420 mm
PageSize::A4	210 × 297 mm
PageSize::A5	148 × 210 mm
PageSize::Letter	215.9 × 279.4 mm
PageSize::Legal	215.9 × 355.6 mm

Dimensioni personalizzate sono supportate tramite PageSize::custom(width, height).

Impostazione Font

TCPDF-Next include i font base PDF standard più la famiglia Unicode-capable DejaVu Sans.

// Font base integrato
$doc->setFont('Helvetica', size: 12);

// Font Unicode integrato
$doc->setFont('DejaVuSans', size: 10);

// Varianti Bold / Italic
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 14);
$doc->setFont('Helvetica', style: FontStyle::BoldItalic, size: 14);

Font Personalizzati

Registra un font TrueType o OpenType, poi usalo tramite il suo alias:

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    $config->addFont('/fonts/Inter-Regular.ttf', alias: 'Inter');
});

$doc->setFont('Inter', size: 11);

Output Testo

TCPDF-Next fornisce quattro metodi per posizionare testo su una pagina. Ognuno serve una diversa esigenza di layout.

cell()

Stampa una cella a riga singola. Ideale per etichette, celle tabella e testo breve:

$doc->cell(
    width: 80,
    height: 10,
    text: 'Invoice #1042',
    border: true,
    align: Align::Center,
);

multiCell()

Stampa testo che va a capo automaticamente entro una larghezza data. Il cursore si sposta in basso dopo ogni chiamata:

$doc->multiCell(
    width: 0,        // 0 = larghezza disponibile completa
    height: 7,
    text: 'This is a longer paragraph that will wrap across multiple lines '
        . 'based on the available width and the current font size.',
);

text()

Posiziona testo in una posizione assoluta (x, y). Non muove il cursore:

$doc->text(x: 105, y: 20, text: 'Centered Title', align: Align::Center);

write()

Scrive testo inline alla posizione corrente del cursore. Supporta link e fluisce naturalmente dentro un paragrafo:

$doc->write(height: 5, text: 'Visit the ');
$doc->write(height: 5, text: 'TCPDF-Next docs', link: 'https://tcpdf-next.dev');
$doc->write(height: 5, text: ' for more information.');

Immagini

Da Percorso File

$doc->imageFromFile(
    path: '/images/logo.png',
    x: 15,
    y: 15,
    width: 40,
);

Da Stringa o Risorsa

$binary = file_get_contents('https://example.com/photo.jpg');

$doc->image(
    data: $binary,
    x: 15,
    y: 60,
    width: 50,
    type: 'JPEG',
);

Formati supportati: PNG, JPEG, GIF, SVG, WebP.

Salvataggio e Output

TCPDF-Next offre diversi modi per recuperare il PDF finale.

Salva su Disco

$doc->save('/reports/invoice-1042.pdf');

Invia a Browser

use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

// Visualizzazione inline (Content-Disposition: inline)
$doc->output('invoice.pdf', OutputDestination::Inline);

// Forza download (Content-Disposition: attachment)
$doc->output('invoice.pdf', OutputDestination::Download);

Ottieni Dati PDF Grezzi

$pdfBytes = $doc->getPdfData();

// Usa con una response PSR-7, un queue job, upload S3, ecc.

Enum OutputDestination

Valore	Comportamento
OutputDestination::Inline	Invia al browser per visualizzazione inline
OutputDestination::Download	Invia al browser come download file
OutputDestination::File	Scrive in un percorso file (usato internamente da save())
OutputDestination::String	Restituisce stringa binaria grezza (usato internamente da getPdfData())

API Fluente

La maggior parte dei setter restituisce $this, abilitando uno stile concatenato e fluente:

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Align;
use Yeeefang\TcpdfNext\Core\Enums\FontStyle;

$pdf = Document::create()
    ->setTitle('Monthly Report')
    ->setAuthor('Acme Corp')
    ->addPage(pageSize: PageSize::A4, orientation: Orientation::Portrait)
    ->setFont('Helvetica', style: FontStyle::Bold, size: 18)
    ->cell(width: 0, height: 15, text: 'Monthly Report — February 2026', align: Align::Center)
    ->ln()
    ->setFont('Helvetica', size: 11)
    ->multiCell(width: 0, height: 6, text: 'This report summarises key metrics...')
    ->save('/reports/monthly.pdf');

Esempio Completo

Mettendo tutto insieme:

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\Align;
use Yeeefang\TcpdfNext\Core\Enums\FontStyle;
use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

$doc = Document::create();

$doc->setTitle('Hello World');
$doc->setAuthor('TCPDF-Next');

$doc->addPage();

// Header
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 20);
$doc->cell(width: 0, height: 15, text: 'Hello, TCPDF-Next!', align: Align::Center);
$doc->ln(20);

// Body
$doc->setFont('DejaVuSans', size: 12);
$doc->multiCell(
    width: 0,
    height: 7,
    text: 'TCPDF-Next is a modern, type-safe PDF generation library for PHP 8.5+. '
        . 'It provides a clean API, strict static analysis, and comprehensive Unicode support.',
);

// Logo
$doc->imageFromFile(path: __DIR__ . '/logo.png', x: 15, y: 80, width: 30);

// Output
$doc->output('hello.pdf', OutputDestination::Download);

Passi Successivi

• Configurazione — ottimizza impostazioni predefinite, crittografia e accessibilità.
• Configurazione — comprendi come Core, Pro e Artisan si integrano insieme.
• FAQ — domande comuni con risposte.