PHP PDFTK

https://github.com/mikehaertl/php-pdftk
Admin
PHP PDFTK is a PHP wrapper library for pdftk that enables PDF manipulation tasks such as form...
Tokens:50,774
Snippets:359
Trust Score:9.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### addFile usage examples

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Examples of adding files with auto-generated handle, explicit handle, and with a password.

```php
$pdf = new Pdf();
$pdf->addFile('/path/to/file1.pdf');        // auto handle 'A'
$pdf->addFile('/path/to/file2.pdf', 'B');   // explicit handle
$pdf->addFile('/path/to/file3.pdf', 'C', 'secret*password');
```

--------------------------------

### Construct Pdf with custom command, locale, and procEnv

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/configuration.md

Example of constructing a Pdf instance with custom options: a custom path to the pdftk binary, a locale for UTF-8 filenames or non-ASCII updateInfo() content, and extra environment variables. The locale must be installed on the system (check with `locale -a` on Linux).

```php
use mikehaertl\pdftk\Pdf;

$pdf = new Pdf('/path/my.pdf', [
    'command' => '/some/other/path/to/pdftk',
    'locale' => 'en_US.utf8',
    'procEnv' => [
        'LANG' => 'en_US.utf-8',
    ],
]);
```

--------------------------------

### Install php-pdftk via Composer

Source: https://github.com/mikehaertl/php-pdftk/blob/master/README.md

Use Composer to install the library. Run this command in your project directory.

```bash
composer require mikehaertl/php-pdftk
```

--------------------------------

### cat() method signature and usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

The cat() method assembles pages from input files. The signature shows parameters: $start, $end, $handle, $qualifier, $rotation. The example demonstrates chaining multiple cat() calls with various page ranges, rotations, and qualifiers, then saving the result.

```php
public function cat(
    int|string|array|null $start = null,
    int|string|null $end = null,
    ?string $handle = null,
    ?string $qualifier = null,
    ?string $rotation = null,
): self
```

```php
$pdf = new Pdf(['A' => '/path/file1.pdf', 'B' => ['/path/file2.pdf', 'pass**word']]);
$result = $pdf->cat(1, 5, 'A')                     // pages 1-5 from A
    ->cat(7, 'end', 'B', null, 'east')             // pages 7-end from B, rotated East
    ->cat('end', 3, 'A', 'even')                   // even pages 3-end in reverse from A
    ->cat([2, 3, 7], 'B')                          // pages 2, 3 and 7 from B
    ->saveAs('/path/new.pdf');
```

--------------------------------

### shuffle() method signature and usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

The shuffle() method interleaves pages from multiple streams. The signature shows parameters similar to cat() but $start is required. The example chains two shuffle() calls and saves the result, with the comment showing the resulting page order.

```php
public function shuffle(
    int|string|array $start,
    int|string|null $end = null,
    ?string $handle = null,
    ?string $qualifier = null,
    ?string $rotation = null,
): self
```

```php
$pdf = new Pdf(['A' => '/path/file1.pdf', 'B' => '/path/file2.pdf']);
$result = $pdf->shuffle(1, 5, 'A')     // pages 1-5 from A
    ->shuffle(3, 8, 'B')               // pages 3-8 from B
    ->saveAs('/path/new.pdf');         // page order A1, B3, A2, B4, A3, B5, ...
```

--------------------------------

### addFile usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Command.md

Shows how to create a Command instance, add two input files with handles 'A' and 'B', and execute the command to produce an output PDF. The second file includes a password with escaped quotes.

```php
$command = new Command();
$command->addFile('/path/to/file1.pdf', 'A');
$command->addFile('/path/to/file2.pdf', 'B', 'complex\'"password');
$command->execute('/path/out.pdf');
```

--------------------------------

### parseBlock static method usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/DataFields.md

Example of calling DataFields::parseBlock() with a sample block and the resulting array.

```php
$block = DataFields::parseBlock("FieldType: Text\nFieldName: Text1\nFieldValue: Hello");
// ['FieldType' => 'Text', 'FieldName' => 'Text1', 'FieldValue' => 'Hello']
```

--------------------------------

### execute method signature and usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Command.md

The execute method signature shows the override. The usage example demonstrates building a fill_form command with an operation argument and an option, then executing it and checking the result. The comment shows the resulting pdftk command.

```php
#[Override]
public function execute($filename = null)
```

```php
$command = new Command();
$command->addFile('/path/form.pdf', 'A');
$command->setOperation('fill_form');
$command->setOperationArgument('/tmp/data.xfdf', true);
$command->addOption('drop_xfa');
if ($command->execute('/tmp/out.pdf')) {
    echo (string) $command; // pdftk 'A'='...' 'fill_form' '...xfdf' 'output' '...' 'drop_xfa'
} else {
    echo $command->getError();
}
```

--------------------------------

### Usage example: getData and updateInfo

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/InfoFields.md

Shows how to retrieve parsed dump_data output, access its values, modify the Info group, and write back with updateInfo().

```php
use mikehaertl\pdftk\Pdf;

$pdf = new Pdf('/path/my.pdf');
$data = $pdf->getData();                    // InfoFields|false
if ($data === false) {
    echo $pdf->getError();
    return;
}

echo (string) $data;                        // raw dump_data output
$arr = $data->__toArray();                  // parsed array
echo $arr['Info']['Creator'];
echo $arr['NumberOfPages'];

// Modify and write back
$data['Info']['Creator'] = 'php-pdftk';
$pdf = new Pdf('/path/my.pdf');
$pdf->updateInfo($data)->saveAs('out.pdf');
```

--------------------------------

### addOption usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Command.md

Demonstrates adding pdftk options: a bare flag 'encrypt_40bit', an option with argument 'allow' set to 'Printing' with escaping disabled, and an option 'owner_pw' with a password that is escaped by default.

```php
$command->addOption('encrypt_40bit');
$command->addOption('allow', 'Printing', false);   // not escaped
$command->addOption('owner_pw', 'complex\'"password'); // escaped per default
```

--------------------------------

### Create XFDF file and fill form

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/XfdfFile.md

Example of creating an XFDF file and using it with Pdf::fillForm(). The XfdfFile object can be saved to a path or passed directly to fillForm().

```php
use mikehaertl\pdftk\XfdfFile;

$xfdf = new XfdfFile(['name' => 'Jürgen мирано']);
$xfdf->saveAs('/path/to/data.xfdf');

// Or use it directly in fillForm() — Pdf does this automatically
$pdf = new Pdf('/path/form.pdf');
$pdf->fillForm($xfdf)->saveAs('filled.pdf');
```

--------------------------------

### updateInfo usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Example of updating PDF metadata by retrieving current info, modifying the Creator field, and saving to a new file.

```php
$pdf = new Pdf('/path/my.pdf');
$data = $pdf->getData();                      // InfoFields
$data['Info']['Creator'] = 'php-pdftk';
$pdf = new Pdf('/path/my.pdf');
$result = $pdf->updateInfo($data)->saveAs('/path/my-new.pdf');
```

--------------------------------

### addPageRange method signature and usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Command.md

The method signature shows the parameters for addPageRange. The usage example demonstrates adding a page range with a handle, qualifier, and rotation, then an array of pages, and executing the command. The resulting pdftk command is shown in the comment.

```php
public function addPageRange(
    int|string|array $start,
    int|string|null $end = null,
    string|null $handle = null,
    string|null $qualifier = null,
    string|null $rotation = null,
)
```

```php
$command = new Command();
$command->addFile('file1.pdf', 'A');
$command->setOperation('cat');
$command->addPageRange(1, 5, 'A', null, 'east');
$command->addPageRange([2, 3, 7], null, 'A');
$command->execute('/path/out.pdf');
// pdftk 'A'='file1.pdf' cat A1-5east A2 A3 A7 'output' '/path/out.pdf'
```

--------------------------------

### fillForm usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Example of filling a PDF form with an array of data, enabling needAppearances for UTF-8 data, and saving the result. Checks for errors if the operation fails.

```php
$pdf = new Pdf('/full/path/to/form.pdf');
$result = $pdf->fillForm(['name' => 'Jürgen', 'nested.name' => 'valX'])
    ->needAppearances()                    // recommended for UTF-8 data
    ->saveAs('filled.pdf');
if ($result === false) {
    $error = $pdf->getError();
}
```

--------------------------------

### parse static method usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/DataFields.md

Example of calling DataFields::parse() with raw dump_data_fields output and accessing the first field's FieldName.

```php
$fields = DataFields::parse($rawDumpDataFieldOutput);
echo $fields[0]['FieldName'];
```

--------------------------------

### Command::__toString() shell command example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/types.md

Example of the full shell command string produced by Command::__toString() when casting a Command object to string. It shows the argument order: input files (handle='filename'), input_pw group, operation with its argument, output filename, and options.

```shell
pdftk 'A'='/path/document1.pdf' 'B'='/path/document2.pdf' 'input_pw' 'B'='complex'"'"'password' cat A1-5 B7-endeast 'output' '/tmp/tmp_php_pdftk_XXXX.pdf' 'drop_xfa' 'need_appearances'
```

--------------------------------

### Combine PDF operations with options (allow, flatten, compress, etc.)

Source: https://github.com/mikehaertl/php-pdftk/blob/master/README.md

Shows chaining multiple PDF operations on a Pdf instance, including permission changes, flattening, compression, ID handling, XFA/XMP dropping, appearance settings, password setting, and encryption strength. Includes examples for filling a form and removing a password. The flatten() method may not work well with UTF-8. The result is false on error, and getError() retrieves the error message.

```php
use mikehaertl\pdftk\Pdf;

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

$result = $pdf->allow('AllFeatures')      // Change permissions
    ->flatten()                 // Merge form data into document (doesn't work well with UTF-8!)
    ->compress($value)          // Compress/Uncompress
    ->keepId('first')           // Keep first/last Id of combined files
    ->dropXfa()                 // Drop newer XFA form from PDF
    ->dropXmp()                 // Drop newer XMP data from PDF
    ->needAppearances()         // Make clients create appearance for form fields
    ->setPassword($pw)          // Set owner password
    ->setUserPassword($pw)      // Set user password
    ->passwordEncryption(128)   // Set password encryption strength
    ->saveAs('new.pdf');
if ($result === false) {
    $error = $pdf->getError();
}

// Example: Fill PDF form and merge form data into PDF
// Fill form with data array
$result = $pdf = new Pdf('/path/form.pdf');
$pdf->fillForm(['name' => 'My Name'])
    ->flatten()
    ->saveAs('/path/filled.pdf');
if ($result === false) {
    $error = $pdf->getError();
}

// Example: Remove password from a PDF
$pdf = new Pdf;
$result = $pdf->addFile('/path/my.pdf', null, 'some**password')
    ->saveAs('/path/new.pdf');
if ($result === false) {
    $error = $pdf->getError();
}
```

--------------------------------

### Usage example with Pdf::getDataFields()

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/DataFields.md

Shows how to obtain DataFields from a Pdf instance, handle errors, and access the raw text, parsed array, and individual fields via array access.

```php
use mikehaertl\pdftk\Pdf;

$pdf = new Pdf('/path/my.pdf');
$data = $pdf->getDataFields();          // DataFields|false
if ($data === false) {
    echo $pdf->getError();
    return;
}

$txt = (string) $data;                  // raw dump_data_fields text
$arr = $data->__toArray();              // parsed blocks
$field1 = $data[0]['FieldName'];        // array access via ArrayObject
```

--------------------------------

### attachFiles() method signature and usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

The attachFiles() method attaches files to the document or a specific page. The signature shows $files and optional $toPage. The example attaches two files to page 7 and saves the result.

```php
public function attachFiles(array $files, ?string $toPage = null): self
```

```php
$pdf = new Pdf('/path/my.pdf');
$result = $pdf->attachFiles(['/path/to/file1', '/path/to/file2'], 7)
    ->saveAs('/path/withfiles.pdf');
```

--------------------------------

### Set custom tempDir for Pdf

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/configuration.md

Example of setting the tempDir property to a custom directory. The pdftk process must be able to write to this directory; this is a workaround for the Ubuntu snap-packaged pdftk that cannot write to /tmp.

```php
use mikehaertl\pdftk\Pdf;

$pdf = new Pdf('/path/my.pdf');
$pdf->tempDir = '/home/john/temp';   // pdftk must be able to write here
```

--------------------------------

### burst() method signature and usage example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

The burst() method splits a PDF into one file per page. The signature shows an optional $filepattern parameter. The example calls burst() with a printf-style pattern and checks the boolean result, retrieving an error via getError() on failure.

```php
public function burst(?string $filepattern = null): bool
```

```php
$result = $pdf->burst('/path/page_%d.pdf');
if ($result === false) {
    $error = $pdf->getError();
}
```

--------------------------------

### Shuffle pages from multiple PDFs

Source: https://github.com/mikehaertl/php-pdftk/blob/master/README.md

Use shuffle() to interleave pages from multiple files. The example creates a new PDF with pages A1, B3, A2, B4, etc. Always check the result for errors.

```php
use mikehaertl\pdftk\Pdf;

$pdf = new Pdf([
    'A' => '/path/file1.pdf',     // A is alias for file1.pdf
    'B' => '/path/file2.pdf',     // B is alias for file2.pdf
]);

// new.pdf will have pages A1, B3, A2, B4, A3, B5, ...
$result = $pdf->shuffle(1, 5, 'A')    // pages 1-5 from A
    ->shuffle(3, 8, 'B')    // pages 3-8 from B
    ->saveAs('/path/new.pdf');
if ($result === false) {
    $error = $pdf->getError();
}
```

--------------------------------

### FdfFile constructor signature

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/FdfFile.md

Constructor signature for FdfFile. Accepts form data as an array, with optional parameters for suffix, prefix, directory, and encoding. The suffix and prefix are ignored and always set to '.fdf' and 'php_pdftk_fdf_' respectively. Throws an exception if the mbstring extension is not installed.

```php
public function __construct(
    array $data,
    ?string $suffix = null,
    ?string $prefix = null,
    ?string $directory = null,
    ?string $encoding = 'UTF-8',
)
```

--------------------------------

### send(?String $filename, bool $inline, array $headers): bool - output PDF to client

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Sends the PDF to the client (inline or download) by triggering execution and delegating to File::send() with content type 'application/pdf'. Header values can be a string, an array of strings for repeated headers, or false to suppress automatic headers like Expires and Content-Length. The example sets the Content-Type and sends the PDF as an attachment with a custom Cache-Control header.

```php
public function send(?string $filename = null, bool $inline = false, array $headers = array()): bool
```

```php
header('Content-Type: application/pdf');
$result = $pdf->send('report.pdf', false, ['Cache-Control' => 'no-cache']);
```

--------------------------------

### toString(): string|bool - get raw PDF binary content

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Triggers the pdftk execution and returns the raw PDF binary content as a string, or false if creation failed. Use to get the PDF for further processing or to write it to a file. The example writes the returned content to result.pdf only if it is not false.

```php
public function toString(): string|bool
```

```php
$content = $pdf->toString();
if ($content !== false) {
    file_put_contents('result.pdf', $content);
}
```

--------------------------------

### Direct InfoFile construction and use

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/InfoFile.md

Demonstrates direct construction of an InfoFile with a custom data array and temporary directory, then passing it to updateInfo(). Useful when you need to control the temp file location.

```php
use mikehaertl\pdftk\InfoFile;

$infoFile = new InfoFile([
    'Info' => ['Title' => 'My Document', 'Creator' => 'php-pdftk'],
    'Bookmark' => [
        ['Title' => 'Chapter 1', 'Level' => 1, 'PageNumber' => 1],
    ],
], null, null, '/path/to/tmpdir');

$pdf = new Pdf('/path/input.pdf');
$result = $pdf->updateInfo($infoFile)->saveAs('/path/output.pdf');
```

--------------------------------

### Create Pdf instance with files, handles, and passwords

Source: https://github.com/mikehaertl/php-pdftk/blob/master/README.md

Shows various ways to create a Pdf instance: with a single file, adding files later with autogenerated handles, adding files with custom handles and passwords, and passing an array to the constructor. Handles must be one or more upper case letters in pdftk 2.x.

```php
// Create an instance for a single file
$pdf = new Pdf('/path/to/form.pdf');

// Alternatively add files later. Handles are autogenerated in this case.
$pdf = new Pdf();
$pdf->addFile('/path/to/file1.pdf');
$pdf->addFile('/path/to/file2.pdf');

// Add files with own handle
$pdf = new Pdf();
$pdf->addFile('/path/to/file1.pdf', 'A');
$pdf->addFile('/path/to/file2.pdf', 'B');
// Add file with handle and password
$pdf->addFile('/path/to/file3.pdf', 'C', 'secret*password');

// Shortcut to pass all files to the constructor
$pdf = new Pdf([
  'A' => ['/path/to/file1.pdf', 'secret*password1'],
  'B' => ['/path/to/file2.pdf', 'secret*password2'],
]);
```

--------------------------------

### Create Pdf with multiple files and passwords

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Creates a Pdf instance with multiple files. Each array value provides the file path and an optional password.

```php
new Pdf([
    'A' => ['/path/to/file1.pdf', 'secret*password1'],
    'B' => ['/path/to/file2.pdf', 'secret*password2'],
]);
```

--------------------------------

### Pass options to shell command (command, useExec)

Source: https://github.com/mikehaertl/php-pdftk/blob/master/README.md

Shows how to pass options to the underlying shell command via the constructor's second argument. Useful for specifying a custom pdftk path or enabling useExec on Windows systems where execution may fail.

```php
use mikehaertl\pdftk\Pdf;

$pdf = new Pdf('/path/my.pdf', [
    'command' => '/some/other/path/to/pdftk',
    // or on most Windows systems:
    // 'command' => 'C:\Program Files (x86)\PDFtk\bin\pdftk.exe',
    'useExec' => true,  // May help on Windows systems if execution fails
]);
```

--------------------------------

### Pdf::__construct

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Creates a new Pdf instance, optionally with a PDF file, another Pdf instance, or an array of files. Options are passed to the underlying Command object.

```APIDOC
## Pdf::__construct

### Description
Creates a new Pdf instance, optionally with a PDF file, another Pdf instance, or an array of files. Options are passed to the underlying Command object.

### Method
Constructor

### Signature
```php
public function __construct(string|Pdf|array|null $pdf = null, array $options = array())
```

### Parameters
- **$pdf** (string|Pdf|array|null) - Optional - A PDF filename, a Pdf instance, or an array of files indexed by handle. If an array, each element can be a string (file path) or an array with file path and password.
- **$options** (array) - Optional - Options passed to Command::setOptions().

### Example
```php
new Pdf([
    'A' => ['/path/to/file1.pdf', 'secret*password1'],
    'B' => ['/path/to/file2.pdf', 'secret*password2'],
]);
```
```

--------------------------------

### Usage of stamp() and multiBackground()

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Shows usage of stamp() and multiBackground() to apply overlays and backgrounds, saving the result with saveAs().

```php
$result = $pdf->stamp('/path/overlay.pdf')->saveAs('/path/stamped.pdf');
$result = $pdf->multiBackground('/path/back_pages.pdf')->saveAs('/path/watermarked.pdf');
```

--------------------------------

### parseData input and output

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/XfdfFile.md

Example input and output of parseData(). Dot notation keys are expanded into nested arrays, and field-name keys are prefixed with underscore to distinguish numeric keys.

```php
[
    'a' => 'value a',
    'b.x' => 'value b.x',
    'd' => ['m1', 'm2'],
]
```

```php
[
    '_a' => 'value a',
    '_b' => ['_x' => 'value b.x'],
    '_d' => [0 => 'm1', 1 => 'm2'],
]
```

--------------------------------

### InfoFile constructor signature

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/InfoFile.md

Constructor signature for InfoFile. Accepts data as an array or InfoFields object, with optional suffix, prefix, directory, and encoding parameters. Throws an exception if encoding is not UTF-8 and the mbstring extension is missing.

```php
public function __construct(
    array|InfoFields $data,
    ?string $suffix = null,
    ?string $prefix = null,
    ?string $directory = null,
    ?string $encoding = 'UTF-8',
)
```

--------------------------------

### addPageRange

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Command.md

Adds a page range to the operation argument for `cat`/`shuffle` operations. Supports both scalar and array start values, with optional end, handle, qualifier, and rotation parameters.

```APIDOC
## addPageRange

### Description
Adds a page range to the operation argument as used by the `cat` / `shuffle` operations. Throws `\Exception` ("Operation was already executed") if the command was already executed.

### Method
PHP method

### Signature
```php
public function addPageRange(
    int|string|array $start,
    int|string|null $end = null,
    string|null $handle = null,
    string|null $qualifier = null,
    string|null $rotation = null,
)
```

### Parameters
- `$start` (int|string|array) - Required - Start page number or an array of page numbers
- `$end` (int|string|null) - Optional (default: `null`) - End page number or `null` for single page (or list if `$start` is an array)
- `$handle` (string|null) - Optional (default: `null`) - Handle of the file, can be `null` if only one file was added
- `$qualifier` (string|null) - Optional (default: `null`) - `'even'` or `'odd'` or `null`
- `$rotation` (string|null) - Optional (default: `null`) - Rotation to apply to the pages (see [`Pdf::cat`](Pdf.md#cat))

### Return Value
`self` for chaining.

### Example
```php
$command = new Command();
$command->addFile('file1.pdf', 'A');
$command->setOperation('cat');
$command->addPageRange(1, 5, 'A', null, 'east');
$command->addPageRange([2, 3, 7], null, 'A');
$command->execute('/path/out.pdf');
// pdftk 'A'='file1.pdf' cat A1-5east A2 A3 A7 'output' '/path/out.pdf'
```
```

--------------------------------

### Set temporary directory for permission issues

Source: https://github.com/mikehaertl/php-pdftk/blob/master/README.md

Shows how to set the tempDir property to a writable directory when encountering permission issues with the default temporary file location.

```php
use mikehaertl\pdftk\Pdf;

$pdf = new Pdf('/path/my.pdf');
$pdf->tempDir = '/home/john/temp';
```

--------------------------------

### background() method signature

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Applies a PDF as a watermark to the background of a single PDF. Only the first page of the watermark file is used, and the watermark file needs a transparent background. Requires a single input file. Returns self.

```php
public function background(string $file): self
```

--------------------------------

### stamp() method signature

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Adds the first page of the provided PDF as an overlay on a single PDF. The overlay should have a transparent background. Requires a single input file. Returns self.

```php
public function stamp(string $file): self
```

--------------------------------

### InfoFile::__construct

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/InfoFile.md

Constructor for creating a temporary pdftk info file used to update PDF metadata. Accepts an array or InfoFields object and optional file naming and encoding parameters.

```APIDOC
## InfoFile::__construct

### Description
Creates a temporary pdftk info file from an array or InfoFields object. The file is used to update PDF metadata with valid Unicode characters and is removed when the object is destroyed.

### Method
Constructor

### Signature
```php
public function __construct(
    array|InfoFields $data,
    ?string $suffix = null,
    ?string $prefix = null,
    ?string $directory = null,
    ?string $encoding = 'UTF-8',
)
```

### Parameters
- **$data** (array|InfoFields) - Required - Data in the format described below.
- **$suffix** (?string) - Optional - Suffix for the temp file; defaults to `'.txt'`.
- **$prefix** (?string) - Optional - Prefix for the temp file; defaults to `'php_pdftk_info_'`.
- **$directory** (?string) - Optional - Directory for the temp file; autodetected if `null`.
- **$encoding** (?string) - Optional - Encoding of the data. If not `'UTF-8'`, key/value are converted to UTF-8 with `mb_convert_encoding` and HTML-escaped (`ENT_XML1`).

### Throws
- `\Exception` - If `$encoding !== 'UTF-8'` and the `mbstring` extension is missing.

### Data Format
```php
[
    'Info' => [
        'Title' => '...',
        'Author' => '...',
        'Subject' => '...',
        'Keywords' => '...',
        'Creator' => '...',
        'Producer' => '...',
        'CreationDate' => '...',
        'ModDate' => '...',
        'Trapped' => '...',
     ],
     'Bookmark' => [
         ['Title' => '...', 'Level' => ..., 'PageNumber' => ...],
     ],
     'PageMedia' => [ ... ],
     'PageLabel' => [ ... ],
     // ...
]
```

### Example: update metadata
```php
use mikehaertl\pdftk\Pdf;

$pdf = new Pdf('/path/input.pdf');
$data = $pdf->getData();                       // InfoFields
$data['Info']['Creator'] = 'php-pdftk';

$pdf = new Pdf('/path/input.pdf');
$result = $pdf->updateInfo($data)              // creates InfoFile internally
    ->saveAs('/path/output.pdf');
if ($result === false) {
    echo $pdf->getError();
}
```

### Example: direct construction
```php
use mikehaertl\pdftk\InfoFile;

$infoFile = new InfoFile([
    'Info' => ['Title' => 'My Document', 'Creator' => 'php-pdftk'],
    'Bookmark' => [
        ['Title' => 'Chapter 1', 'Level' => 1, 'PageNumber' => 1],
    ],
], null, null, '/path/to/tmpdir');

$pdf = new Pdf('/path/input.pdf');
$result = $pdf->updateInfo($infoFile)->saveAs('/path/output.pdf');
```
```

--------------------------------

### XfdfFile::parseData() input/output example

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/types.md

Shows the transformation performed by XfdfFile::parseData() when converting dot notation to a nested array. Field-name keys are prefixed with an underscore so numeric keys of multi-value arrays remain distinguishable.

```php
input: ['a' => 'value a', 'b.x' => 'v1', 'd' => ['m1', 'm2']]
output: ['_a' => 'value a', '_b' => ['_x' => 'v1'], '_d' => [0 => 'm1', 1 => 'm2']]
```

--------------------------------

### Fill form with replacement font for UTF-8 support

Source: https://github.com/mikehaertl/php-pdftk/blob/master/README.md

When using pdftk-java >= 3.3.0 and the embedded font does not support UTF-8 characters, use replacementFont() to specify a local font. This example fills a form with data and sets the replacement font.

```php
use mikehaertl\pdftk\Pdf;

// Fill form with data array
$pdf = new Pdf('/full/path/to/form.pdf');
$result = $pdf->fillForm($data)
    ->replacementFont('/usr/share/fonts/dejavu/DejaVuSans.ttf')
    ->saveAs('filled.pdf');
```

--------------------------------

### parse static method signature

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/DataFields.md

Parses the output of dump_data_fields into an array. The input can be a single block of Name: value lines or a set of blocks separated by lines starting with ---. Blocks are only split when a --- line is followed by FieldType:.

```php
public static function parse(string $input): array
```

--------------------------------

### multiStamp() method signature

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Adds a PDF as a page-by-page overlay. If the provided file is shorter, the last page is repeated. Unlike stamp(), there is no single-file guard. Returns self.

```php
public function multiStamp(string $file): self
```

--------------------------------

### Consumer pattern for runtime failure handling

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/errors.md

Consumer pattern for handling runtime failures: methods return false on failure, and the error message is retrieved via $pdf->getError(). This example shows chaining fillForm(), needAppearances(), and saveAs(), then checking the result and throwing a RuntimeException with the error message.

```php
use mikehaertl\pdftk\Pdf;

$pdf = new Pdf('/path/form.pdf');
$result = $pdf->fillForm(['name' => 'Jürgen'])
    ->needAppearances()
    ->saveAs('filled.pdf');

if ($result === false) {
    throw new RuntimeException('PDF processing failed: ' . $pdf->getError());
}
```

--------------------------------

### Get PDF data with Pdf::getData(), getDataFields(), and data conversion

Source: https://github.com/mikehaertl/php-pdftk/blob/master/README.md

Reads metadata or form field information. getData() returns metadata, getDataFields() returns form fields. The returned object can be echoed, cast to string, or cast to array. Returns false on error; check getError().

```php
use mikehaertl\pdftk\Pdf;

// Get data
$pdf = new Pdf('/path/my.pdf');
$data = $pdf->getData();
if ($data === false) {
    $error = $pdf->getError();
}

// Get form data fields
$pdf = new Pdf('/path/my.pdf');
$data = $pdf->getDataFields();
if ($data === false) {
    $error = $pdf->getError();
}

// Get data as string
echo $data;
$txt = (string) $data;
$txt = $data->__toString();

// Get data as array
$arr = (array) $data;
$arr = $data->__toArray();
$field1 = $data[0]['Field1'];

```

--------------------------------

### parseBlock static method signature

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/DataFields.md

Parses a single block of Name1: Value1 lines. Lines matching /([^:]*): ?(.*)/ become array entries keyed by name. Repeating keys are converted to arrays. Multiline values for FieldValue and FieldValueDefault continue on the next line unless the line starts with FieldValue:, FieldValueDefault:, or FieldJustification:.

```php
public static function parseBlock(string $block): array
```

--------------------------------

### multiStamp

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Adds a PDF as an overlay page-by-page, repeating the last page if needed.

```APIDOC
## `multiStamp`

### Description
Adds a PDF as an overlay page-by-page. If the overlay file has fewer pages, the last page is repeated. Unlike `stamp()`, there is no single-file guard.

### Method
`public function multiStamp(string $file): self`

### Parameters
- `$file` (string) - Required - Path to the PDF file to use as overlay.

### Returns
`self` - Returns the current instance for method chaining.

### Example
```php
$pdf->multiStamp('/path/overlay_pages.pdf');
```
```

--------------------------------

### Usage of getData()

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Shows how to call getData() and handle the returned InfoFields object or false. Access fields via ArrayObject syntax.

```php
$data = $pdf->getData();
if ($data === false) {
    echo $pdf->getError();
} else {
    echo $data['Info']['Creator'];      // ArrayObject access
}
```

--------------------------------

### Usage of getDataFields()

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Shows how to call getDataFields() and iterate over the returned DataFields object, printing each field name and value.

```php
$data = $pdf->getDataFields();
if ($data === false) {
    echo $pdf->getError();
} else {
    foreach ($data as $field) {
        echo $field['FieldName'] . ': ' . ($field['FieldValue'] ?? '(empty)') . PHP_EOL;
    }
}
```

--------------------------------

### Perform multiple operations by feeding one Pdf instance into another

Source: https://github.com/mikehaertl/php-pdftk/blob/master/README.md

Shows how to chain operations: extract pages with cat() and then use the resulting Pdf as source for a new Pdf to fill a form. Only one operation can be performed on a single Pdf instance, so this pattern is required for multiple operations. Returns false on error; check getError().

```php
use mikehaertl\pdftk\Pdf;

// Extract pages 1-5 and 7,4,9 into a new file
$pdf = new Pdf('/path/my.pdf');
$pdf->cat(1, 5)
    ->cat([7, 4, 9]);

// We now use the above PDF as source file for a new PDF
$pdf2 = new Pdf($pdf);
$result = $pdf2->fillForm(['name' => 'ÄÜÖ äüö мирано čárka'])
    ->needAppearances()
    ->saveAs('/path/filled.pdf');
if ($result === false) {
    $error = $pdf->getError();
}

```

--------------------------------

### cat

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Assemble pages from input files using the cat operation.

```APIDOC
## cat

### Description
Assemble (catenate) pages from the input files; sets `cat` operation and appends each call's range via `Command::addPageRange()`.

### Method
`cat`

### Signature
```php
public function cat(
    int|string|array|null $start = null,
    int|string|null $end = null,
    ?string $handle = null,
    ?string $qualifier = null,
    ?string $rotation = null,
): self
```

### Parameters
- `$start` (int|string|array|null) - Optional - Start page, array of pages (ignores other args), or `null` = all pages of all files
- `$end` (int|string|null) - Optional - End page (may be `'end'`); `null` = single page / list
- `$handle` (?string) - Optional - File handle; may be `null` with a single file
- `$qualifier` (?string) - Optional - `'even'` or `'odd'`
- `$rotation` (?string) - Optional - Rotation — see below

### Rotation Values
- `north` 0, `east` 90, `south` 180, `west` 270, `left` −90, `right` +90, `down` +180 (`left`/`right`/`down` are relative adjustments). Older pdftk uses `N/E/S/W/L/R/D`. `$start` may be greater than `$end` for reverse order.

### Returns
`self`

### Example
```php
$pdf = new Pdf(['A' => '/path/file1.pdf', 'B' => ['/path/file2.pdf', 'pass**word']]);
$result = $pdf->cat(1, 5, 'A')                     // pages 1-5 from A
    ->cat(7, 'end', 'B', null, 'east')             // pages 7-end from B, rotated East
    ->cat('end', 3, 'A', 'even')                   // even pages 3-end in reverse from A
    ->cat([2, 3, 7], 'B')                          // pages 2, 3 and 7 from B
    ->saveAs('/path/new.pdf');
```
```

--------------------------------

### XfdfFile::__construct

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/XfdfFile.md

Constructor for creating a temporary XFDF file from form data.

```APIDOC
## Constructor

### Description
Creates a temporary XFDF file from form data. The file is written immediately and removed when the object is destroyed.

### Method
Constructor

### Signature
```php
public function __construct(
    array $data,
    ?string $suffix = null,
    ?string $prefix = null,
    ?string $directory = null,
    ?string $encoding = 'UTF-8',
)
```

### Parameters
- **$data** (array) - Required - Form data as field name → value (see format below)
- **$suffix** (?string) - Optional - Suffix for the temp file; defaults to `'.xfdf'`
- **$prefix** (?string) - Optional - Prefix for the temp file; defaults to `'php_pdftk_xfdf_'`
- **$directory** (?string) - Optional - Directory where the file is created; autodetected (`self::getTempDir()`) if `null`
- **$encoding** (?string) - Optional - Encoding of the data; non-UTF-8 data is converted with `mb_convert_encoding` if available

### Data Format
```
[
    // Field name => field value
    'Firstname' => 'John',

    // Hierarchical/nested fields in dot notation
    'Address.Street' => 'Some Street',
    'Address.City' => 'Any City',

    // Multi value fields
    'Pets' => ['Cat', 'Mouse'],
]
```

### Example
```php
use mikehaertl\pdftk\XfdfFile;

$xfdf = new XfdfFile(['name' => 'Jürgen мирано']);
$xfdf->saveAs('/path/to/data.xfdf');

// Or use it directly in fillForm() — Pdf does this automatically
$pdf = new Pdf('/path/form.pdf');
$pdf->fillForm($xfdf)->saveAs('filled.pdf');
```
```

--------------------------------

### Files array (constructor of Pdf)

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/types.md

Documentation for the files array parameter passed to the Pdf constructor.

```APIDOC
## Files array (constructor of `Pdf`)

### Description
Passed as `$pdf` to `Pdf::__construct()`; keys are handles (one or more uppercase letters `A..Z` in pdftk 2.x), values are filenames/instances or `[filename, password]` pairs. Strings and `Pdf` instances are also accepted for a single input file.

### Method
Constructor

### Endpoint
`Pdf::__construct()`

### Parameters
#### Constructor Parameter
- **$pdf** (array|string|Pdf) - Required - Files array or a single file string/Pdf instance.

### Request Example
```php
[
    'A' => '/path/to/file1.pdf',                  // string value
    'B' => ['/path/to/file2.pdf', 'pass**word'],  // array value: [file, password]
    'C' => $anotherPdfInstance,                   // Pdf instance value
]
```

### Response
#### Success Response
No return value (constructor).

### Notes
Parsed by `Pdf::__construct()` (`src/Pdf.php:104-112`): array values are unpacked as `addFile($file[0], $handle, $file[1])`.
```

--------------------------------

### Add overlay PDF with Pdf::stamp() and Pdf::multiStamp()

Source: https://github.com/mikehaertl/php-pdftk/blob/master/README.md

Adds another PDF as an overlay. stamp() repeats the first page; multiStamp() uses one page per page. Both return false on error; check getError().

```php
use mikehaertl\pdftk\Pdf;

// Stamp with another PDF (first page repeated)
$pdf = new Pdf('/path/my.pdf');
$result = $pdf->stamp('/path/overlay.pdf')
    ->saveAs('/path/stamped.pdf');
if ($result === false) {
    $error = $pdf->getError();
}

// Stamp with another PDF (one page each)
$pdf = new Pdf('/path/my.pdf');
$result = $pdf->multiStamp('/path/overlay_pages.pdf')
    ->saveAs('/path/stamped.pdf');
if ($result === false) {
    $error = $pdf->getError();
}

```

--------------------------------

### multiBackground() method signature

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Applies a PDF as a page-by-page background. If the provided file has fewer pages, the last page is repeated. Unlike background(), there is no single-file guard. Returns self.

```php
public function multiBackground(string $file): self
```

--------------------------------

### toString

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Returns the raw PDF binary content.

```APIDOC
## toString

### Description
Returns the raw PDF binary content as a string, or `false` if creation failed. Triggers execution.

### Method
toString

### Signature
public function toString(): string|bool

### Return Value
- **string|bool** - The raw PDF binary content as a string, or `false` on failure.

### Example
```php
$content = $pdf->toString();
if ($content !== false) {
    file_put_contents('result.pdf', $content);
}
```
```

--------------------------------

### Pdf constructor signature

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Constructor signature for the Pdf facade. Accepts a filename, a Pdf instance, or an array of files indexed by handle, plus options passed to Command::setOptions().

```php
public function __construct(string|Pdf|array|null $pdf = null, array $options = array())
```

--------------------------------

### InfoFields::__construct

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/InfoFields.md

Creates a new InfoFields instance, optionally parsing raw dump_data output.

```APIDOC
## InfoFields::__construct

### Description
Creates a new InfoFields instance, optionally parsing raw dump_data output.

### Method
Constructor

### Signature
php
public function __construct(
    ?string $input = null,
    int $flags = 0,
    string $iterator_class = "ArrayIterator",
)


### Parameters
- **$input** (?string) - Optional - The raw dump_data output to parse
- **$flags** (int) - Optional - Standard ArrayObject flags
- **$iterator_class** (string) - Optional - Standard ArrayObject iterator class

### Source
`src/InfoFields.php:28`
```

--------------------------------

### Chain option setters with saveAs()

Source: https://github.com/mikehaertl/php-pdftk/blob/master/_autodocs/api-reference/Pdf.md

Shows how to chain option setters with an operation and saveAs(). Each setter returns self and appends a pdftk option. Note that flatten() cannot be combined with needAppearances() and works poorly with UTF-8 data; replacementFont() requires pdftk-java >= 3.3.0.

```php
$result = $pdf->allow('Assembly CopyContents')  // permissions
    ->flatten()                                 // merge form data into document (not UTF-8-safe)
    ->compress(false)                           // uncompress
    ->keepId('first')                           // keep first/last ID of combined files
    ->dropXfa()                                 // drop newer XFA form
    ->dropXmp()                                 // drop newer XMP data
    ->needAppearances()                         // clients render form field appearance
    ->setPassword($pw)                          // owner password
    ->setUserPassword($pw)                      // user password
    ->passwordEncryption(128)                   // encrypt_128bit / encrypt_40bit
    ->replacementFont('/usr/share/fonts/dejavu/DejaVuSans.ttf') // pdftk-java >= 3.3.0
    ->saveAs('new.pdf');
```
Tokens:
Raw