README

A lightweight PHP library for converting PDF documents to image files. Supports JPG, PNG, and GIF output formats with optional image scaling and whitespace trimming.

Key Principles

• Simple static API - Single method call to convert PDF to image
• Multiple formats - Supports JPG, PNG, and GIF output formats
• Image manipulation - Optional scaling and whitespace trimming built-in
• Zero dependencies - Only requires PHP 8.0+ and the Imagick extension
• Auto-directory creation - Automatically creates output directories if they don't exist
• Strict typing - Fully typed with PHP 8 strict mode enabled

Architecture

The library follows a clean, minimal architecture with three main components:

┌─────────────────────────────────────────────────────────────┐
│                      User Application                       │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Configuration                            │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • pdfPath      - Source PDF file path               │    │
│  │ • savePath     - Output image file path             │    │
│  │ • format       - Output format (jpg/png/gif)        │    │
│  │ • trim         - Remove whitespace borders          │    │
│  │ • cols/rows    - Scale dimensions                   │    │
│  │ • bestfit      - Maintain aspect ratio on scale     │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       Convertor                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ convert(Configuration): void                        │    │
│  │   ├── Validates Imagick availability                │    │
│  │   ├── Loads PDF via Imagick                         │    │
│  │   ├── Applies format conversion                     │    │
│  │   ├── Applies optional scaling                      │    │
│  │   ├── Applies optional trimming                     │    │
│  │   └── Writes output file to disk                    │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   ConvertorException                         │
│  Custom exception for all conversion-related errors          │
└─────────────────────────────────────────────────────────────┘

Components

📦 Installation

It's best to use Composer for installation, and you can also find the package on Packagist and GitHub.

To install, simply use the command:

$ composer require baraja-core/php-pdf-to-image

Requirements

• PHP 8.0 or higher
• Imagick extension (ext-imagick)

Installing Imagick

On Debian/Ubuntu:

$ sudo apt-get install php-imagick

On macOS with Homebrew:

$ brew install imagemagick
$ pecl install imagick

Make sure Ghostscript is also installed for PDF processing:

# Debian/Ubuntu
$ sudo apt-get install ghostscript

# macOS
$ brew install ghostscript

Basic Usage

Simple Conversion

The most straightforward way to convert a PDF to an image:

use Baraja\PdfToImage\Configuration;
use Baraja\PdfToImage\Convertor;

$configuration = new Configuration(
    pdfPath: '/path/to/document.pdf',
    savePath: '/path/to/output.jpg',
    format: 'jpg'
);

Convertor::convert($configuration);

Using the Factory Method

You can also use the static factory method for configuration:

use Baraja\PdfToImage\Configuration;
use Baraja\PdfToImage\Convertor;

$configuration = Configuration::from(
    pdfPath: '/path/to/document.pdf',
    savePath: '/path/to/output.png',
    format: 'png',
    trim: true
);

Convertor::convert($configuration);

Converting with Image Scaling

To resize the output image during conversion:

use Baraja\PdfToImage\Configuration;
use Baraja\PdfToImage\Convertor;

$configuration = new Configuration(
    pdfPath: '/path/to/document.pdf',
    savePath: '/path/to/thumbnail.jpg',
    format: 'jpg',
    cols: 800,    // Width in pixels
    rows: 600,    // Height in pixels
    bestfit: true // Maintain aspect ratio
);

Convertor::convert($configuration);

Trimming Whitespace

To automatically remove white borders from the resulting image:

use Baraja\PdfToImage\Configuration;
use Baraja\PdfToImage\Convertor;

$configuration = new Configuration(
    pdfPath: '/path/to/document.pdf',
    savePath: '/path/to/trimmed.png',
    format: 'png',
    trim: true
);

Convertor::convert($configuration);

Full Example with Error Handling

use Baraja\PdfToImage\Configuration;
use Baraja\PdfToImage\Convertor;
use Baraja\PdfToImage\ConvertorException;

try {
    $configuration = new Configuration(
        pdfPath: __DIR__ . '/documents/report.pdf',
        savePath: __DIR__ . '/images/report-preview.jpg',
        format: 'jpg',
        trim: true,
        cols: 1200,
        rows: 900,
        bestfit: true
    );

    Convertor::convert($configuration);

    echo 'PDF converted successfully!';
} catch (ConvertorException $e) {
    echo 'Conversion failed: ' . $e->getMessage();
}

Configuration Options

Supported Output Formats

The library provides constants for supported formats:

use Baraja\PdfToImage\Configuration;

Configuration::FormatJpg;  // 'jpg'
Configuration::FormatPng;  // 'png'
Configuration::FormatGif;  // 'gif'

Configuration::SupportedFormats; // ['jpg', 'png', 'gif']

How It Works

1. Configuration Validation - When you create a Configuration object, it validates:

   • The PDF file exists at the specified path
   • The output format is one of the supported formats (jpg, png, gif)
   • Format strings are normalized to lowercase

2. Conversion Process - When Convertor::convert() is called:

   • Verifies the Imagick extension is available
   • Loads the first page of the PDF using Imagick
   • Sets the output image format
   • Applies scaling if cols and rows are specified
   • Applies trimming if enabled (removes white borders with 1px tolerance)
   • Creates the output directory if it doesn't exist
   • Writes the image to disk with 0666 permissions

3. Error Handling - All errors are wrapped in ConvertorException:

   • File not found errors
   • Imagick processing errors
   • File write permission errors
   • Directory creation errors

Important Notes

• First Page Only - The converter processes only the first page of multi-page PDF documents
• Memory Usage - Large PDF files or high-resolution outputs may require significant memory. Adjust PHP's memory_limit if needed
• Ghostscript - Imagick requires Ghostscript to be installed for PDF processing
• Static Class - The Convertor class is static and cannot be instantiated

Author

Jan Barášek - https://baraja.cz

📄 License

baraja-core/php-pdf-to-image is licensed under the MIT license. See the LICENSE file for more details.