Quick Start

This guide covers the fundamental workflow of php-pdftk: instantiating the class, providing input files, selecting an operation, and handling the output.

The Core Workflow

Every operation in php-pdftk follows a standard four-step lifecycle:

  1. Initialization: Create a Pdf instance.
  2. Input: Define one or more source PDF files.
  3. Configuration: Call a single operation method (e.g., fillForm, cat, burst) and apply optional modifiers (e.g., flatten, allow).
  4. Execution: Trigger the operation by saving the file to disk, sending it to the browser, or capturing it as a string.

Step 1 & 2: Creating an Instance and Adding Files

Under the hood, pdftk requires an alphanumeric "handle" (like A, B, C) for every input file it processes. php-pdftk can manage these automatically, or you can assign them manually if your operation requires strict referencing.

Single File (Auto-Handle)

If you are manipulating a single document, pass the path directly to the constructor:

use mikehaertl\pdftk\Pdf;

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

Multiple Files (Auto-Handles)

If you add files sequentially without handles, the library assigns them automatically (using A, B, C, etc.).

$pdf = new Pdf();
$pdf->addFile('/path/to/cover.pdf');
$pdf->addFile('/path/to/content.pdf');

Multiple Files (Explicit Handles)

For operations like cat (concatenation) or shuffle, explicit handles allow you to specify exactly which pages come from which files.

$pdf = new Pdf();
$pdf->addFile('/path/to/document1.pdf', 'DOC1');
$pdf->addFile('/path/to/document2.pdf', 'DOC2', 'optional_password');

// Or using the array shortcut in the constructor:
$pdf = new Pdf([
    'DOC1' => '/path/to/document1.pdf',
    'DOC2' => ['/path/to/document2.pdf', 'optional_password'],
]);

Step 3 & 4: Operations and Execution

Once files are attached, define what you want to do. Let's look at a basic example: applying a background watermark and saving the result.

Saving to Disk (saveAs)

The saveAs() method compiles the pdftk command, executes it via the shell, and copies the resulting temporary file to your specified destination.

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

// Apply a background (Step 3)
$pdf->background('/path/to/watermark.pdf');

// Execute and Save (Step 4)
if (!$pdf->saveAs('/path/to/output.pdf')) {
    // ALWAYS check the return value. 
    // If it fails, getError() contains the raw shell error.
    error_log("PDFtk Error: " . $pdf->getError());
}

Sending to the Browser (send)

In web applications, you often want to serve the generated PDF directly to the user without leaving artifacts on the server.

$pdf = new Pdf('/path/to/source.pdf');
$pdf->fillForm(['Name' => 'Alice']);

// Force a file download dialog in the browser
$pdf->send('Alice_Document.pdf');

// Display inline in the browser (useful for previews)
// The second argument `true` forces inline rendering.
$pdf->send('Alice_Document.pdf', true);

// Send inline without a specific filename
$pdf->send();

Capturing as a String (toString)

If you need to store the generated PDF in a database, attach it to an email using a library like PHPMailer, or upload it to AWS S3, you can capture the raw binary string.

$pdf = new Pdf('/path/to/source.pdf');
$pdf->fillForm(['Name' => 'Bob']);

$binaryContent = $pdf->toString();

if ($binaryContent === false) {
    throw new Exception("Failed to generate PDF: " . $pdf->getError());
}

// Example: Uploading to S3 or saving to DB...
// $s3->putObject(['Body' => $binaryContent, ...]);

Crucial Rule: One Operation per Instance

Because pdftk is a shell command that takes an input, processes it, and halts, you can only call one primary operation method (like background(), fillForm(), cat(), or burst()) per Pdf instance.

If you call $pdf->background('a.pdf')->fillForm($data), the command will fail or behave unpredictably. To perform multiple distinct transformations, you must chain instances.

Continue to Temp Files & Chaining to learn how to handle complex multi-step workflows.