README

A PHP 8.2+ library for extracting text from PDF documents and creating PDFs with intelligent reader/writer selection.

Features

PDF Text Extraction (Readers)

• Multiple PDF Readers with automatic fallback:

  • pdftotext (poppler-utils) - Fast extraction for text-based PDFs
  • PDFBox (Apache, Java) - Better handling of complex layouts
  • Tesseract - OCR for scanned documents
  • OCRmyPDF - High-quality OCR with preprocessing

• Automatic Reader Selection - Tries text extraction first, falls back to OCR if needed

• Caching - Extracted text is cached to avoid redundant processing

• Language Support - Configurable OCR languages (German + English by default)

PDF Creation (Writers)

• Multiple PDF Writers with automatic fallback:

  • Dompdf - HTML to PDF conversion (pure PHP, LGPL)
  • TCPDF - Programmatic PDF creation (pure PHP, LGPL)
  • wkhtmltopdf - High-quality HTML rendering via WebKit (external tool)

• Automatic Writer Selection - Uses the first available writer by priority

• Multiple Input Formats - HTML, plain text, or HTML files

• Metadata Support - Title, author, subject for generated PDFs

• Stationery Overlay - StationeryOverlayWriter places a letterhead PDF as a layer under imported content pages, with separate assets for the first and following pages

Additional Helpers

• Image OCR - TesseractReader::extractTextFromImage() runs OCR on a single image file instead of a PDF
• Encrypted Layers - CipherLayerSolver resolves encrypted content layers so that text extraction also works on protected documents
• Broken ToUnicode Tables - GlyphNameLayer (via PDFTextProvider::glyphNameText()) rebuilds the text layer from the fonts' glyph names, so a PDF whose ToUnicode table maps every glyph to the wrong character still yields its exact text - no OCR, no guessing. Needs mutool (mupdf-tools)

Requirements

• PHP 8.2+

For Text Extraction (at least one)

• pdftotext (apt install poppler-utils)
• tesseract-ocr (apt install tesseract-ocr tesseract-ocr-deu)
• ocrmypdf (apt install ocrmypdf)
• mutool (apt install mupdf-tools) - optional, needed for glyphNameText() on PDFs with broken ToUnicode tables
• Java + PDFBox JAR (optional)

For PDF Creation (at least one)

• dompdf/dompdf (composer require dompdf/dompdf)
• tecnickcom/tcpdf (composer require tecnickcom/tcpdf)
• wkhtmltopdf (apt install wkhtmltopdf)

Installation

Via Composer

composer require daniel-jorg-schuppelius/php-pdf-toolkit

Clone with Submodules

git clone --recurse-submodules https://github.com/Daniel-Jorg-Schuppelius/php-pdf-toolkit.git

Or if already cloned:

git submodule update --init

Install System Dependencies

Use the included install script for system dependencies:

# Install PDF extraction tools (poppler-utils, tesseract, ocrmypdf)
sudo ./installscript/install-dependencies.sh

Install PHP Libraries for PDF Creation

# Dompdf (recommended, pure PHP)
composer require dompdf/dompdf

# Or TCPDF (alternative, pure PHP)
composer require tecnickcom/tcpdf

# Or wkhtmltopdf (external tool, best quality)
sudo apt install wkhtmltopdf

Usage

Text Extraction

use PDFToolkit\Registries\PDFReaderRegistry;

$registry = PDFReaderRegistry::getInstance();
$document = $registry->extractText('/path/to/file.pdf', [
    'language' => 'deu+eng'
]);

if ($document->hasText()) {
    echo $document->text;
    echo "Reader: " . $document->reader;
    echo "Scanned: " . ($document->isScanned ? 'Yes' : 'No');
}

// Ohne OCR-Fallback (schneller für Text-PDFs wie Kontoauszüge)
$document = $registry->extractTextOnly('/path/to/bankstatement.pdf', [
    'layout' => false  // Ohne Layout-Formatierung für bessere Regex-Extraktion
]);

PDF Creation

use PDFToolkit\Registries\PDFWriterRegistry;
use PDFToolkit\Entities\PDFContent;

$registry = PDFWriterRegistry::getInstance();

// Simple: HTML to PDF
$registry->htmlToPdf('<h1>Hello World</h1><p>Content</p>', '/path/to/output.pdf');

// Simple: Text to PDF
$registry->textToPdf('Plain text content', '/path/to/output.pdf');

// Advanced: With metadata and options
$content = PDFContent::fromHtml($html, [
    'title' => 'My Document',
    'author' => 'John Doe',
    'subject' => 'Example PDF'
]);

$registry->createPdf($content, '/path/to/output.pdf', [
    'paper_size' => 'A4',
    'orientation' => 'portrait',
    'margins' => ['top' => 15, 'bottom' => 15, 'left' => 15, 'right' => 15]
]);

// Use specific writer
$registry->createPdf($content, '/path/to/output.pdf', [], 'dompdf');

// Get PDF as string (for download/streaming)
$pdfString = $registry->createPdfString($content);
header('Content-Type: application/pdf');
echo $pdfString;

Check Available Tools

// Readers
$readerRegistry = PDFReaderRegistry::getInstance();
foreach ($readerRegistry->getReaderInfo() as $info) {
    echo "{$info['name']}: " . ($info['available'] ? '✓' : '✗') . "\n";
}
}

// Writers
$writerRegistry = PDFWriterRegistry::getInstance();
foreach ($writerRegistry->getWriterInfo() as $info) {
    echo "{$info['name']}: " . ($info['available'] ? '✓' : '✗') . "\n";
}

Configuration

Tool paths can be configured in config/executables.json:

{
    "shellExecutables": {
        "pdftotext": {
            "path": "/usr/bin/pdftotext",
            "required": true
        },
        "wkhtmltopdf": {
            "path": "/usr/bin/wkhtmltopdf",
            "required": false
        }
    }
}

Architecture

PDFReaderRegistry → [Readers by Priority] → PDFDocument
                          ↓
              PDFToTextReader (10)     # Fast, for text PDFs
              PDFBoxReader (30)        # Complex layouts
              TesseractReader (50)     # OCR for scans
              OcrMyPDFReader (60)      # Best OCR quality

PDFWriterRegistry → [Writers by Priority] → PDF File
                          ↓
              DompdfWriter (10)        # HTML→PDF, pure PHP
              TcpdfWriter (20)         # Programmatic, pure PHP
              WkhtmltopdfWriter (30)   # Best HTML rendering

License

AGPL-3.0-or-later - see LICENSE file.

Versions

Releases are tagged in Git; git tag --sort=-v:refname lists them (latest: v0.17.2). There is no separate changelog file — the tags and the commit history are the record.