Configuration & Environment

Under the hood, php-pdftk leverages the mikehaertl/php-shellcommand library to execute the pdftk binary securely via PHP's proc_open().

You can deeply customize how this shell execution occurs by passing an array of options as the second argument to the Pdf constructor.

Customizing the Shell Command

If pdftk is not in your system's global PATH, or if you have multiple versions installed and want to target a specific one, you can provide the exact path using the command option.

use mikehaertl\pdftk\Pdf;

$options = [
    // Target a specific binary on Linux
    'command' => '/opt/pdftk/bin/pdftk',

    // On Windows, target the executable
    // 'command' => 'C:\Program Files (x86)\PDFtk\bin\pdftk.exe',
];

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

The useExec Flag (Windows)

On some Windows environments, proc_open() can behave inconsistently or hang during execution. If you experience execution failures on Windows, you can instruct the underlying shell command library to fall back to PHP's standard exec() function.

$options = [
    'command' => 'C:\Program Files (x86)\PDFtk\bin\pdftk.exe',
    'useExec' => true, 
];
$pdf = new Pdf('/path/to/my.pdf', $options);

Locales and UTF-8 Filenames

If your application processes files that have UTF-8 characters in their actual filenames, or if you are passing an InfoFile with UTF-8 metadata to updateInfo(), the shell process executing pdftk must be aware that it should expect UTF-8 input.

If the shell's environment defaults to a non-UTF-8 locale (like C or POSIX), pdftk may fail to read the files or garble the metadata.

You can explicitly set the LANG environment variable and the system locale for the process:

$options = [
    'locale' => 'en_US.utf8',
    'procEnv' => [
        'LANG' => 'en_US.utf-8',
    ],
];

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

Troubleshooting Locales: Ensure that the locale you specify (en_US.utf8 in this example) is actually compiled and installed on your host OS. On Linux, you can verify available locales by running locale -a via SSH.