Page Manipulation

php-pdftk provides robust tools for rearranging, combining, extracting, and splitting PDF pages. These operations map directly to the cat, shuffle, and burst commands in the underlying pdftk binary.

Combine & Extract Pages (cat)

The cat() method is highly versatile. It allows you to extract specific pages from a single document, or concatenate (stitch together) pages from multiple different documents into a new file.

Method Signature:

cat($start = null, $end = null, $handle = null, $qualifier = null, $rotation = null)

• $start / $end: Page numbers (integers), or the string 'end'. If $start is an array of pages, the other arguments are ignored.
• $handle: The specific file handle to pull from (e.g., 'A').
• $qualifier: 'even' or 'odd' (e.g., to extract only even pages for double-sided printing).
• $rotation: Rotate the extracted pages. Valid values are north (0), east (90), south (180), west (270). Note: left, right, and down apply relative rotations.

Scenario 1: Extracting from a Single File

Extract the first 5 pages, plus page 9, and save them as a new document.

use mikehaertl\pdftk\Pdf;

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

$pdf->cat(1, 5)          // Pages 1 through 5
    ->cat([9])           // Page 9 specifically
    ->saveAs('/path/to/executive_summary.pdf');

Scenario 2: Merging Multiple Files

If you want to merge three entire documents together in sequence:

$files = ['cover.pdf', 'chapter1.pdf', 'chapter2.pdf'];
$pdf = new Pdf($files);

// Calling cat() with no arguments processes all pages from all files in order
$pdf->cat()->saveAs('complete_book.pdf');

Scenario 3: Complex Multi-File Assembly

You can explicitly control which pages come from which files using handles, and even rotate specific pages on the fly.

$pdf = new Pdf([
    'DOC_A' => '/path/file_a.pdf',
    'DOC_B' => '/path/file_b.pdf',
]);

$pdf->cat(1, 5, 'DOC_A')                     // Pages 1-5 from DOC_A
    ->cat(3, null, 'DOC_B', null, 'east')    // Page 3 from DOC_B, rotated 90 degrees
    ->cat('end', 10, 'DOC_A', 'even')        // Even pages, backwards from the end down to page 10
    ->saveAs('/path/assembled.pdf');

Interleaving Pages (shuffle)

While cat appends blocks of pages sequentially, shuffle() creates "streams" of pages and pulls one page from each stream iteratively. This is incredibly useful for collating documents—for example, if you scanned the front sides of a stack of papers into one PDF, and the back sides into another.

use mikehaertl\pdftk\Pdf;

$pdf = new Pdf([
    'FRONTS' => '/path/front_pages.pdf',
    'BACKS'  => '/path/back_pages.pdf',
]);

// Output order: FRONTS_1, BACKS_1, FRONTS_2, BACKS_2, FRONTS_3, BACKS_3...
$pdf->shuffle(1, 'end', 'FRONTS')
    ->shuffle(1, 'end', 'BACKS')
    ->saveAs('/path/collated_document.pdf');

Splitting a Document (burst)

The burst() method takes a single PDF and splits it, creating a separate file for every single page. This is heavily used in data pipelines where each page of a batch PDF needs to be processed individually.

use mikehaertl\pdftk\Pdf;

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

// Supply a printf() pattern for the filenames.
// %04d ensures names like invoice_0001.pdf, invoice_0002.pdf
$result = $pdf->burst('/path/output/invoice_%04d.pdf'); 

if ($result === false) {
    echo "Failed to burst PDF: " . $pdf->getError();
}

If you omit the file pattern, it defaults to pg_%04d.pdf in the current working directory.