Temporary Files & Chaining Operations

To master php-pdftk, you must understand two fundamental architectural realities of the pdftk binary: it relies entirely on physical files, and it only performs one task at a time.

Managing Temporary Files

Because PHP arrays and objects cannot be passed directly into a shell executable, php-pdftk automatically writes data to intermediate files (like .xfdf data files), executes pdftk to output a new .pdf file in the system's temporary directory, and then moves that file to your desired destination during saveAs().

By default, the library uses sys_get_temp_dir() to figure out where to write these files.

Customizing the Temporary Directory

In some restrictive hosting environments, or due to sandboxing (like the Ubuntu snap installation), PHP might not have permission to write to /tmp, or pdftk might not have permission to read from it.

You can explicitly define a writable directory for intermediate files by setting the $tempDir property immediately after instantiation.

use mikehaertl\pdftk\Pdf;

$pdf = new Pdf('/path/to/my.pdf');

// Ensure this folder exists and is writable by both PHP and pdftk
$pdf->tempDir = '/var/www/html/app/storage/tmp';

// Operations will now use the custom temp directory safely
$pdf->fillForm(['Name' => 'John'])->saveAs('/path/to/final.pdf');

Reading Raw Temporary Output

If you don't want to save the final PDF to disk (e.g., you want to stream it to an AWS S3 bucket directly), you can call execute() to run the command, and then grab the contents of the generated temporary file.

$pdf = new Pdf('/path/to/my.pdf');
$pdf->fillForm(['name' => 'My Name'])->execute();

if ($pdf->getError()) {
    throw new Exception($pdf->getError());
}

// Access the temporary file wrapper directly
$tmpFilePath = (string) $pdf->getTmpFile();
$content = file_get_contents($tmpFilePath);

Alternatively, use the convenience method toString() which handles execution and reading for you:

$content = $pdf->toString();

Chaining Multiple Operations

pdftk is a strict pipeline tool. You cannot tell it to extract a page (cat) AND fill a form (fillForm) in a single shell command.

If you attempt to call two primary operations on the same Pdf instance, the library will either overwrite your first command or throw an error.

To perform multi-step workflows, you must "feed" the result of one Pdf object into a new Pdf object. php-pdftk makes this elegant: you can pass a Pdf instance directly into the constructor of another.

Example: Extract, Rotate, then Fill

Let's say we have a 10-page document. We want to extract page 1, rotate it, and then fill a form on that specific extracted page.

use mikehaertl\pdftk\Pdf;

// --- Step 1: Extract and Rotate ---
$pdf1 = new Pdf('/path/to/original.pdf');
// Extract page 1 and rotate it East (90 degrees)
$pdf1->cat(1, null, null, null, 'east');

// --- Step 2: Fill Form on the Result ---
// Passing $pdf1 as the source automatically triggers $pdf1->execute()
// and uses its temporary output file as the input for $pdf2.
$pdf2 = new Pdf($pdf1);

$result = $pdf2->fillForm(['EmployeeName' => 'John Doe'])
     ->needAppearances()
     ->saveAs('/path/to/final.pdf');

if ($result === false) {
    echo "Workflow failed: " . $pdf2->getError();
}

This chaining mechanism ensures that file handles and temporary files are managed correctly without leaving orphaned data on your disk.