README

A lightweight PHP document merging library designed for practical backend workflows and legacy PDF compatibility handling.

This library allows multiple document types—including Word, Excel, images, and existing PDFs—to be consolidated into a single PDF output through a unified processing pipeline.

Unlike many PDF merging utilities that fail on newer PDF structures, this library automatically normalizes incompatible PDF versions using Ghostscript preprocessing to maintain compatibility with legacy PHP PDF ecosystems such as FPDF, FPDI, and mPDF.

Features

• Merge multiple file formats into a single PDF
• Automatic PDF compatibility normalization using Ghostscript
• Handles mixed document ingestion workflows
• Supports PDF metadata configuration
• Optional PDF permission restrictions
• Lightweight and framework-friendly
• Designed for internal systems and document automation pipelines

Supported File Types

• DOC
• DOCX
• XLS
• XLSX
• JPG
• JPEG
• PNG
• PDF

Why Ghostscript Is Required

Many PHP PDF libraries such as FPDI, FPDF, and mPDF have limitations when importing or merging PDFs generated with newer PDF specifications (commonly PDF 1.5+).

This library automatically preprocesses incompatible PDFs through Ghostscript to:

• Normalize PDF versions
• Improve merge compatibility
• Prevent parser/import failures
• Avoid dependency on commercial PDF parser addons

Ghostscript is therefore a mandatory dependency.

Current Limitations

Embedded Images Inside DOC/DOCX

Images embedded inside .doc or .docx files are currently not supported during conversion.

Maintenance Status

This project is currently in maintenance mode.
No major feature updates are planned at the moment.

Required PHP Extension

The mbstring extension is required.

Installation

Install the package via Composer:

composer require virdiggg/merge-files

Ghostscript Installation

Install Ghostscript and ensure the gs command is globally accessible from your terminal or command prompt.

Official installation guide:

https://ghostscript.readthedocs.io/en/latest/Install.html

Verify installation:

gs

Expected output:

GPL Ghostscript 10.xx.x
GS>

Basic Usage

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use Virdiggg\MergeFiles\Merge;

try {

    $mf = new Merge();

    $mf->setAuthor('Me');
    $mf->setCreator('Also Me');

    $mf->setOutputName('mergedpdf.pdf');
    $mf->setOutputPath(__DIR__ . '/output/');

    $mf->setTitle('Merged PDF');
    $mf->setSubject('Merged PDF');

    // Optional
    // $mf->setKeywords(['pdf', 'word', 'excel', 'image']);

    // Required if permissions are used
    // $mf->setPassword('password');

    // Optional permissions
    // $mf->setPermissions(['copy']);

    $files = [
        __DIR__.'/input/new_pdf.pdf',
        __DIR__.'/input/Book1.xlsx',
        __DIR__.'/input/download.pdf',
        __DIR__.'/input/word.docx',
        __DIR__.'/input/Wikipedia-logo-v2.png'
    ];

    $mf->mergeToPDF($files);

} catch (Exception $e) {

    echo "Error: " . $e->getMessage();

}

PDF Permissions

You may configure PDF permissions using the following options.

Passing an empty array [] will disable all permissions, preventing actions such as copying, printing, modifying, or extracting content from the generated PDF.

Available permissions:

• copy
• print
• modify
• annot-forms
• fill-forms
• extract
• assemble
• print-highres

Example:

$mf->setPermissions([
    'copy',
    'print'
]);

Disable all permissions:

$mf->setPermissions([]);

Recommended Use Cases

This library is suitable for:

• Internal document automation systems
• Batch PDF consolidation workflows
• Compliance document generation
• Office document archival pipelines
• Backend administrative systems
• Legacy PHP applications requiring PDF normalization

Notes

This project prioritizes compatibility and operational reliability over minimal external dependencies.

If your workflow involves handling PDFs from unpredictable external sources, Ghostscript preprocessing significantly improves merge stability and interoperability across different PDF generators.