Transazioni (TransactionManager)

Le transazioni ti consentono di prendere uno snapshot dello stato documento, renderizzare contenuto speculativamente, e poi decidere se mantenere o scartare il risultato. Questo è il meccanismo primario per logica layout "try-fit".

Panoramica API

Metodo	Descrizione	Restituisce
startTransaction()	Prendi uno snapshot dello stato documento corrente	static
commitTransaction()	Scarta lo snapshot e mantieni tutte le modifiche	static
rollbackTransaction()	Ripristina il documento allo snapshot	static

Tutti e tre i metodi restituiscono static per concatenazione fluente.

Come Funziona

Quando chiami startTransaction(), il TransactionManager memorizza una copia completa dello stato documento corrente — posizione cursore, conteggio pagine, buffer contenuto e contatori interni. Poi renderizzi contenuto come normale.

• Commit scarta lo snapshot memorizzato. Il contenuto renderizzato rimane nel documento.
• Rollback sostituisce lo stato corrente con lo snapshot memorizzato. Tutto renderizzato da startTransaction() è scartato.

Esempio Base

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12);

// Prova ad adattare un blocco sulla pagina corrente
$pdf->startTransaction();
$startPage = $pdf->getPage();
$pdf->multiCell(0, 6, $longText);

if ($pdf->getPage() > $startPage) {
    // Contenuto traboccato alla pagina successiva — rollback e prova diversamente
    $pdf->rollbackTransaction();
    $pdf->addPage();
    $pdf->multiCell(0, 6, $longText);
} else {
    // Contenuto si adatta — mantienilo
    $pdf->commitTransaction();
}

Casi d'Uso

Adattare Contenuto in Spazio Rimanente

Il caso d'uso più comune è controllare se il contenuto si adatta sulla pagina corrente prima di committarlo:

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 10);

foreach ($sections as $section) {
    $pdf->startTransaction();
    $startPage = $pdf->getPage();

    $pdf->setFont('Helvetica', 'B', 14)
        ->cell(0, 8, $section['title'], newLine: true)
        ->setFont('Helvetica', '', 10)
        ->multiCell(0, 5, $section['body']);

    if ($pdf->getPage() > $startPage) {
        $pdf->rollbackTransaction();
        $pdf->addPage();
        $pdf->setFont('Helvetica', 'B', 14)
            ->cell(0, 8, $section['title'], newLine: true)
            ->setFont('Helvetica', '', 10)
            ->multiCell(0, 5, $section['body']);
    } else {
        $pdf->commitTransaction();
    }
}

Misurare Altezza Contenuto

Usa una transazione per misurare quanto spazio verticale consumerà il contenuto senza effettivamente posizionarlo:

$pdf->startTransaction();
$startY = $pdf->getY();
$pdf->multiCell(0, 5, $text);
$endY = $pdf->getY();
$height = $endY - $startY;
$pdf->rollbackTransaction();

// Ora usa $height per decisioni layout

Vincoli Importanti

Nessun Annidamento

Le transazioni annidate non sono supportate. Chiamare startTransaction() mentre una transazione è già attiva lancerà un'eccezione. Sempre commit o rollback prima di iniziare una nuova transazione.

Impatto Performance

Una transazione memorizza uno snapshot completo dello stato documento. Per documenti con molte pagine e buffer contenuto grandi, questo può temporaneamente raddoppiare l'uso memoria. Mantieni blocchi transazione piccoli quanto possibile — snapshot, renderizza, decidi, poi commit o rollback immediatamente.

Best Practice

• Mantieni il codice tra startTransaction() e commitTransaction() / rollbackTransaction() minimale.
• Assicura sempre che ogni startTransaction() sia accoppiato con esattamente un commitTransaction() o rollbackTransaction().
• Non eseguire I/O file o inviare output dentro un blocco transazione — solo mutazioni documento possono essere rolled back.
• Preferisci misurare sezioni piccole piuttosto che avvolgere generazione intera documento in una transazione.