README

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

📖 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.