DeclarationTVA/docs/PDFTK_INSTALLATION.md

PDFTK Installation Guide

This guide explains how to install PDFTK (PDF Toolkit) on different operating systems to enable automatic PDF form field filling in the DeclarationTVA module.

⚠️ IMPORTANT: Never Install PDFTK as Root

CRITICAL WARNING: Never install PDFTK as root or with sudo. This will cause permission issues and the web server won't be able to access it. Always install PDFTK as a regular user.

What is PDFTK?

PDFTK is a command-line tool that can manipulate PDF files, including filling form fields. It's the most reliable way to programmatically fill PDF forms.

Installation by Operating System

Linux (Ubuntu/Debian)

Method 1: Using apt (Recommended)

# Update package list
sudo apt update

# Install pdftk (system-wide installation)
sudo apt install pdftk

# Verify installation
pdftk --version

Note: System-wide installation via apt is fine as it installs to /usr/bin/pdftk which is accessible to all users.

Method 2: Using snap

# Install via snap
sudo snap install pdftk

# Verify installation
pdftk --version

Method 3: Manual installation (if apt fails)

# Download pdftk package
wget https://gitlab.com/pdftk-java/pdftk/-/releases/v3.3.3/downloads/pdftk-java-3.3.3-1.deb

# Install the package
sudo dpkg -i pdftk-java-3.3.3-1.deb

# Fix any dependencies
sudo apt-get install -f

# Verify installation
pdftk --version

Note: Manual installation via dpkg is also fine as it installs to system directories.

Linux (CentOS/RHEL/Fedora)

Method 1: Using yum/dnf

# For CentOS/RHEL 7
sudo yum install pdftk

# For CentOS/RHEL 8+ and Fedora
sudo dnf install pdftk

# Verify installation
pdftk --version

Method 2: Using snap

# Install snapd first (if not installed)
sudo yum install snapd
# or
sudo dnf install snapd

# Enable snapd
sudo systemctl enable --now snapd.socket

# Install pdftk
sudo snap install pdftk

# Verify installation
pdftk --version

macOS

Method 1: Using Homebrew (Recommended)

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install pdftk (installs to user directory)
brew install pdftk-java

# Verify installation
pdftk --version

Note: Homebrew installs to user directories by default, which is perfect for web server access.

Method 2: Using MacPorts

# Install MacPorts if not already installed
# Download from: https://www.macports.org/install.php

# Install pdftk
sudo port install pdftk

# Verify installation
pdftk --version

Method 3: Manual installation

# Download pdftk-java
curl -L -o pdftk.tar.gz https://gitlab.com/pdftk-java/pdftk/-/releases/v3.3.3/downloads/pdftk-java-3.3.3-mac.zip

# Extract and install
unzip pdftk.tar.gz
sudo mv pdftk-java-3.3.3-mac/pdftk /usr/local/bin/
sudo chmod +x /usr/local/bin/pdftk

# Verify installation
pdftk --version

Windows

Method 1: Using Chocolatey (Recommended)

# Install Chocolatey if not already installed
# Run PowerShell as Administrator and execute:
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install pdftk
choco install pdftk

# Verify installation
pdftk --version

Method 2: Using Scoop

# Install Scoop if not already installed
# Run PowerShell and execute:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

# Install pdftk
scoop install pdftk

# Verify installation
pdftk --version

Method 3: Manual installation

1. Download pdftk-java from: https://gitlab.com/pdftk-java/pdftk/-/releases
2. Extract the ZIP file
3. Add the extracted folder to your Windows PATH environment variable
4. Open Command Prompt and verify: pdftk --version

Docker

If you're running Dolibarr in Docker, you can install pdftk in your Docker container:

# Add to your Dockerfile
RUN apt-get update && apt-get install -y pdftk

Or run it in an existing container:

# Enter the container
docker exec -it your-dolibarr-container bash

# Install pdftk
apt-get update && apt-get install -y pdftk

# Verify installation
pdftk --version

Verification

After installation, verify that pdftk is working:

# Check if pdftk is available
which pdftk

# Check version
pdftk --version

# Test with a simple command
pdftk --help

Troubleshooting

Common Issues

1. "pdftk: command not found"

• Solution: Make sure pdftk is in your PATH environment variable
• Linux/macOS: Add /usr/local/bin or /usr/bin to your PATH
• Windows: Add the pdftk installation directory to your PATH

2. "Permission denied" errors

• Solution: Make sure the pdftk executable has proper permissions
• Linux/macOS: sudo chmod +x /usr/local/bin/pdftk
• Windows: Run Command Prompt as Administrator

3. "Web server cannot access pdftk" (MOST COMMON)

• Problem: PDFTK installed as root, web server user cannot access it
• Solution:
  • Option A: Reinstall as regular user (recommended)
  • Option B: Copy pdftk to accessible location: sudo cp /usr/bin/pdftk /tmp/pdftk && sudo chmod +x /tmp/pdftk
  • Option C: Create symbolic link: sudo ln -s /usr/bin/pdftk /tmp/pdftk

4. Java-related errors

• Solution: pdftk-java requires Java. Install Java if not present:
  • Linux: sudo apt install openjdk-11-jre (or similar)
  • macOS: brew install openjdk@11
  • Windows: Download from Oracle or use choco install openjdk

5. "No such file or directory" errors

• Solution: Verify the pdftk installation path and ensure it's executable

Testing PDF Form Filling

Test if pdftk can fill your PDF forms:

# Create a simple test FDF file
echo "%FDF-1.2
1 0 obj
<<
/FDF
<<
/Fields [
<<
/T (test_field)
/V (Test Value)
>>
]
>>
>>
endobj
trailer
<<
/Root 1 0 R
>>
%%EOF" > test.fdf

# Test filling a PDF form
pdftk your_template.pdf fill_form test.fdf output test_output.pdf

# Check if the output was created
ls -la test_output.pdf

Module Integration

Once pdftk is installed, the DeclarationTVA module will automatically:

1. Detect pdftk availability using which pdftk
2. Use pdftk for form filling when available
3. Fall back to manual approach when pdftk is not available

Benefits of Using PDFTK

• ✅ Reliable form filling - Actually fills PDF form fields
• ✅ No coordinate mapping - Uses field names directly
• ✅ Layout independent - Works with any PDF layout
• ✅ Professional output - Maintains PDF structure and formatting
• ✅ Wide compatibility - Works with most PDF types

⚠️ Font Settings Limitation

Important: PDFTK may not preserve the exact font settings of your PDF form fields. This is a limitation of the PDF form filling process, not the module. To ensure consistent formatting:

1. Set all fields to the same font in your PDF template
2. Use standard fonts (Arial, Helvetica, Times) for better compatibility
3. Test the output to ensure the formatting meets your requirements

✅ Font Settings Solution

Good News: The module now forces consistent font settings for all PDF form fields!

Official Document Formatting

The module automatically applies professional formatting suitable for official documents:

• Font: Courier New 9pt
• Color: Black
• Alignment: Left-aligned
• Consistent formatting across all form fields

Benefits:

1. Professional appearance suitable for official documents
2. Consistent formatting across all form fields
3. No font inconsistencies between different fields
4. Standardized layout for government submissions

Alternative Solutions

If you cannot install pdftk, the module provides:

1. Manual filling approach - Generates data files for manual PDF filling
2. Template copying - Provides the original PDF template
3. Data reference - Comprehensive data files with all values

Support

For issues with pdftk installation:

1. Check the official documentation: https://gitlab.com/pdftk-java/pdftk
2. Verify system requirements: Java 8+ is required for pdftk-java
3. Test with simple PDFs before using complex forms
4. Check file permissions and PATH environment variables

Security Notes

• File permissions: Ensure pdftk has appropriate permissions
• Temporary files: The module cleans up temporary FDF files automatically
• Path validation: The module validates file paths before processing
• Error handling: Comprehensive error handling for security

---

Note: This module cannot automatically install pdftk due to system security restrictions. Manual installation is required as described above.