Watermarks & Overlays

php-pdftk allows you to composite PDFs on top of one another. This is the standard method for applying company letterheads, "Draft" watermarks, or approval stamps.

For these operations to work, the primary PDF must have transparent areas (e.g., standard text on a transparent background, not a solid white box).

Backgrounds (Underlay)

A background operation places the secondary PDF behind the content of your primary PDF. This is typically used for applying stationary, letterheads, or subtle background watermarks.

Single Background (background)

The background() method takes the first page of the provided background PDF and applies it to every page of your primary PDF.

use mikehaertl\pdftk\Pdf;

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

// Apply the company letterhead to every page
$pdf->background('/path/to/letterhead_template.pdf')
    ->saveAs('/path/to/final_invoice.pdf');

Multi-Background (multiBackground)

If your stationary has a distinct first page (e.g., containing a large header logo) and subsequent pages (e.g., just footer text), use multiBackground().

This method maps pages 1-to-1: Page 1 of the background applies to Page 1 of the primary document, Page 2 to Page 2, and so on. If the background PDF has fewer pages than the primary PDF, the last page of the background is repeated for all remaining pages.

use mikehaertl\pdftk\Pdf;

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

// multi_page_letterhead.pdf has a unique page 1, and a standard page 2.
$pdf->multiBackground('/path/to/multi_page_letterhead.pdf')
    ->saveAs('/path/to/watermarked_report.pdf');

Overlays (Stamp)

A stamp operation places the secondary PDF on top of the content of your primary PDF. This is used when the mark must obscure the content beneath it, such as a large "VOID", "PAID", or "CONFIDENTIAL" stamp, or a digital signature overlay.

Single Overlay (stamp)

The stamp() method takes the first page of the overlay PDF and applies it to every page of the primary PDF.

use mikehaertl\pdftk\Pdf;

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

// Stamp "CONFIDENTIAL" on top of every page
$pdf->stamp('/path/to/confidential_stamp.pdf')
    ->saveAs('/path/to/stamped_contract.pdf');

Multi-Overlay (multiStamp)

Similar to multi-background, multiStamp() applies pages sequentially. This is highly useful for applying specific data to specific pages, like applying pagination (Page 1 of X) or dynamic barcodes to a pre-existing batch PDF.

use mikehaertl\pdftk\Pdf;

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

// barcode_overlays.pdf contains a unique barcode per page
$pdf->multiStamp('/path/to/barcode_overlays.pdf')
    ->saveAs('/path/to/processed_batch.pdf');

Best Practice: When creating stamp PDFs, ensure they are exactly the same dimensions (e.g., A4 or US Letter) as the primary PDF, with the stamp graphic positioned exactly where you want it to appear, and the rest of the page left fully transparent.