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)
```bash
# 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
```bash
# Install via snap
sudo snap install pdftk

# Verify installation
pdftk --version
```

#### Method 3: Manual installation (if apt fails)
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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)
```powershell
# 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
```powershell
# 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:

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

Or run it in an existing container:
```bash
# 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:

```bash
# 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:

```bash
# 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.