Try out before you actually use it

docker run --pull always -p 9090:80 treineticprojects/demo_opensource:latest

PDFLib v3.1

The most advanced, driver-based PDF manipulation library for PHP.

PDFLib v3.1 is the mature, stable release of the new driver-based architecture. It allows you to switch between powerful backends like Ghostscript, PDFtk, OpenSSL, and Tesseract for different tasks, all under a single, beautiful fluent API.

👉 Try the Interactive Demo | 📚 Read the Documentation

---

🛡️ Stability Guarantee (v4.0 Ready)

We take backward compatibility seriously.

The v3.1 architecture introduces a strict separation between the API (Facade) and the Execution Logic (Drivers).

• Zero Breaking Changes Promise: This structure allows us to upgrade the underlying engine (e.g., adding Cloud/Async support in v4.0) without changing a single line of your application code.
• Pipeline Pattern: Operations like rotate() or ocr() are queued, decoupling your intent from immediate execution. Use PDFLib with confidence knowing the API is frozen and stable.

🚀 What's New in v3.1?

• OCR Support: Extract text from images and PDFs using Tesseract.
• Redaction: Securely blackout sensitive text.
• Metadata: Read/Write PDF metadata.
• Laravel Wrapper: First-party ServiceProvider and Facade.
• Stateful Chaining: Queue multiple operations (->rotate()->watermark()->save()).

📦 Requirements

• PHP >= 8.1
• Ghostscript >= 9.16 (for GhostscriptDriver)
• Google Chrome or Chromium (for HTML to PDF)
• pdftk (PDF Toolkit) (for Form Filling)

Quick Start: Run ./bin/install-dependencies to automatically install these tools.

👉 See Installation Guide for detailed setup instructions on macOS, Ubuntu, and Windows.

🔧 Installation

composer require imal-h/pdf-box

✨ Features

Feature	Description	Driver
HTML to PDF	Generate PDF from HTML/CSS	Chrome
Digital Sign	Sign PDFs with X.509 Certs	OpenSSL
OCR	Extract text from PDF/Images	Tesseract
Redact	Blackout sensitive text	Ghostscript
Fill Forms	Fill AcroForms (FDF)	PDFtk
Inspect Forms	Get Field Names	PDFtk
Convert	PDF to Images (PNG/JPG)	Ghostscript
Merge	Combine multiple PDFs	Ghostscript
Split	Extract pages or ranges	Ghostscript
Compress	Optimize PDF file size	Ghostscript
Encrypt	Password protection and permissions	Ghostscript
Watermark	Overlay text on pages	Ghostscript
Rotation	Rotate pages 90/180/270°	Ghostscript
Metadata	Edit Title, Author, Keywords	Ghostscript
Flatten	Burn forms into content	Ghostscript

📖 Usage

HTML to PDF (New in v3.0)

Generate PDFs from HTML content or URLs using Chrome Headless.

use ImalH\PDFLib\PDF;

// From HTML String
PDF::init()
    ->driver(PDF::DRIVER_CHROME)
    ->convertFromHtml('<h1>Hello World</h1>', 'output.pdf');

// From URL (Coming Soon)
// PDF::init()->driver(PDF::DRIVER_CHROME)->fromUrl('https://google.com')->save('output.pdf');

Digital Signatures (New in v3.0)

Digitally sign PDFs using OpenSSL (requires tecnickcom/tcpdf).

use ImalH\PDFLib\PDF;

PDF::init()
    ->driver(PDF::DRIVER_OPENSSL)
    ->from('contract.pdf')
    ->sign('certificate.crt', 'private_key.pem', 'signed_contract.pdf', [
        'info' => [
            'Name' => 'John Doe',
            'Location' => 'Colombo, LK',
            'Reason' => 'Digital Contract Signature'
        ],
        // New in v3.2: Visual Signature with Relative Positioning
        'image' => 'signature.png',
        'page' => 1,
        'x' => ($pdf->getPageDimensions(1)['w'] - 60) / 2, // Center X
        'y' => 250,
        'w' => 60,
        'h' => 30
    ]);

Note: If you use a self-signed certificate (like in testing), PDF viewers will show "Signature Validity Unknown". For a green "Trusted" checkmark, use a certificate issued by a recognized Certificate Authority (CA) or explicitly trust your self-signed certificate in the viewer's settings.

Laravel Integration

Publish the config file:

php artisan vendor:publish --tag=pdflib-config

Use the Facade in your controllers:

use ImalH\PDFLib\Laravel\Facades\PDF;

// The driver is automatically configured from config/pdflib.php
PDF::from('upload.pdf')->ocr('output.txt');

OCR (New in v3.1)

Extract text from scanned PDFs or images.

PDF::init()
    ->driver(PDF::DRIVER_TESSERACT)
    ->from('scanned_doc.pdf') // Automatically converts PDF to Image internally
    ->ocr('extracted_text');

Redaction (New in v3.1)

Permanently remove sensitive text.

PDF::init()
    ->driver(PDF::DRIVER_GHOSTSCRIPT)
    ->from('invoice.pdf')
    ->redact('Confidential', 'clean_invoice.pdf');

Interactive Forms

Fill PDF forms programmatically using pdftk.

use ImalH\PDFLib\PDF;

// 1. Inspect Fields (Optional)
$fields = PDF::init()->driver(PDF::DRIVER_PDFTK)->getFormFields('form_template.pdf');
// returns ['full_name', 'date', ...]

// 2. Fill Form
PDF::init()
    ->driver(PDF::DRIVER_PDFTK)
    ->from('form_template.pdf')
    ->fillForm([
        'full_name' => 'Imal Perera',
        'date' => '2025-01-01'
    ], 'filled_form.pdf');

The Modern Way (Fluent API)

use ImalH\PDFLib\PDF;

// Convert PDF Page 1 to JPEG
PDF::init()
    ->driver(PDF::DRIVER_GHOSTSCRIPT)
    ->from('document.pdf')
    ->to('output_folder')
    ->convert();

The Legacy Way (v2.x Facade)

Existing code continues to work without changes, but is marked as deprecated.

use ImalH\PDFLib\PDFLib; // Legacy Class

$pdfLib = new PDFLib();
$pdfLib->setPdfPath("document.pdf")
       ->setOutputPath("output_folder")
       ->convert();

Example: Advanced Chain

PDF::init()
    ->from('source.pdf')
    ->from('source.pdf')
    ->encrypt('userPass', 'ownerPass', 'processed.pdf');

(Note: Current driver operations like encrypt, rotate, and watermark are immediate and require a destination path. Fully stateful chaining for these methods is planned for v3.1)

🔮 Roadmap

Want to see what's coming next (v3.1+)? Check out our Roadmap.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING for details on our new coding standards (Pint, PHPStan) and architecture.

📄 License

The MIT License (MIT). Please see License File.

---

Initiative of Treinetic (Pvt) Ltd.