README

A comprehensive PDF generation library for Laravel and PHP applications with advanced features including multi-page support, custom page breaks, headers/footers, watermarks, bookmarks, and full styling capabilities.

🌟 Features

🚀 Multi-page Support - Handle large documents with automatic pagination
📄 Custom Page Breaks - Break pages anywhere you want, even within tables
📊 Table Pagination - Smart table breaking with repeated headers (<thead>)
🔢 Page Numbering - Automatic dynamic page numbering (Page {PAGE_NUM} of {PAGE_COUNT}) rendered via native Dompdf canvas scripts
📋 Headers & Footers - Customizable headers and footers with automated @page top/bottom margin calculation to eliminate text overlap
🎨 Advanced Styling - Full CSS support including Microsoft Word-like formatting
💧 Watermarks - Add opacity-controlled, rotated CSS watermarks to your PDFs
🔖 Bookmarks - Create PDF bookmarks for navigation
📝 Metadata - Set PDF metadata (title, author, subject, etc.)
🛡️ Typed Exceptions - Custom PdfGenerationException thrown on invalid paper sizes, orientation errors, or file save failures
⚡ Performance & Octane Ready - Transient container bindings (SimPdfServiceProvider) and explicit resetState() to prevent cross-request state pollution in long-running processes (Swoole, Octane, Queue workers)

🚀 Installation

Packagist Installation (Recommended)

# Install from Packagist
composer require sim-pdf/sim-pdf-libs

# Publish config (optional)
php artisan vendor:publish --provider="SimPdf\SimPdfLibs\SimPdfServiceProvider" --tag="config"

Git Installation

# Install from Git repository
composer config repositories.sim-pdf vcs https://github.com/5u00n/sim-pdf-libs
composer require sim-pdf/sim-pdf-libs:dev-main

For step-by-step setup guides, refer to INSTALLATION.md.

🎯 Quick Start

Basic PDF (3 lines using Facade)

use SimPdf\SimPdfLibs\Facades\SimPdf;

$html = '<h1>Hello World</h1><p>This is a PDF!</p>';
return SimPdf::loadHtml($html)->download('document.pdf');

Global Helper (`simpdf()`)

// Use the ultra-concise global helper function anywhere in your app:
return simpdf('<h1>Hello World</h1>')->setPaper('A4')->download('document.pdf');

Save Directly to Storage Disk (`saveToDisk()`)

// Save to AWS S3, Google Cloud, or local Laravel Storage disk:
SimPdf::loadHtml($html)->saveToDisk('invoices/2026/inv-101.pdf', 's3');

Laravel Blade Directives (`@pageBreak`, `@noBreak`)

<h1>Section 1</h1>

@pageBreak

<h1>Section 2</h1>

@noBreak
    <div>This block will not be split across page breaks</div>
@endNoBreak

🎯 When to Use SimPDF

✅ Perfect For:

📊 Reports & Invoices - Professional business documents
📋 Contracts & Legal Docs - Multi-page documents with headers/footers
📚 Manuals & Guides - Large documents with bookmarks and page numbers
📈 Data Reports - Tables with pagination and custom breaks
🎨 Styled Documents - Microsoft Word-like formatting
📄 Forms & Applications - Complex layouts with styling
📑 Catalogs & Brochures - Multi-page marketing materials
📊 Financial Statements - Professional financial documents

❌ Not Ideal For:

🖼️ Image-heavy PDFs - Use specialized image-to-PDF tools
📱 Interactive PDFs - Use Adobe Acrobat or similar
🎬 Video/Audio PDFs - Use multimedia PDF tools
📊 Complex Charts - Use chart-specific libraries first

🚀 Best Use Cases:

1. Business Reports

// Perfect for monthly/quarterly reports
SimPdf::loadHtml($reportHtml)
    ->setPaper('A4', 'portrait')
    ->enablePageNumbers()
    ->setHeader('Monthly Report - ' . date('F Y'))
    ->setFooter('Confidential - Page {PAGE_NUM}')
    ->download('monthly-report.pdf');

2. Invoice Generation

// Perfect for invoices with line items
SimPdf::loadHtml($invoiceHtml)
    ->breakTable(['repeat_header' => true])
    ->setHeader('INVOICE #' . $invoiceNumber)
    ->setFooter('Payment due within 30 days')
    ->download('invoice.pdf');

3. User Manuals

// Perfect for documentation with bookmarks
SimPdf::loadHtml($manualHtml)
    ->addBookmark('Introduction', 1)
    ->addBookmark('Installation', 1)
    ->addBookmark('Configuration', 1)
    ->addBookmark('Troubleshooting', 1)
    ->enablePageNumbers()
    ->download('user-manual.pdf');

📚 Real-World Usage Examples

1. Employee Report Card

// Perfect for HR reports with multiple pages
$html = view('reports.employee-card', [
    'employee' => $employee,
    'performance' => $performanceData,
    'goals' => $goals
])->render();

return SimPdf::loadHtml($html)
    ->setPaper('A4', 'portrait')
    ->enablePageNumbers(['position' => 'bottom-center'])
    ->setHeader('Employee Performance Report')
    ->setFooter('Confidential - HR Department')
    ->addWatermark('CONFIDENTIAL', ['opacity' => 0.1])
    ->download('employee-report-' . $employee->id . '.pdf');

2. Product Catalog

// Perfect for e-commerce catalogs
$html = view('catalog.products', [
    'products' => $products,
    'categories' => $categories
])->render();

return SimPdf::loadHtml($html)
    ->setPaper('A4', 'portrait')
    ->breakTable(['repeat_header' => true, 'min_rows' => 3])
    ->setHeader('Product Catalog 2026')
    ->setFooter('Visit our website for more products')
    ->addBookmark('Electronics', 1)
    ->addBookmark('Clothing', 1)
    ->addBookmark('Home & Garden', 1)
    ->download('product-catalog.pdf');

3. Financial Statement

// Perfect for financial documents
$html = view('financial.statement', [
    'revenue' => $revenueData,
    'expenses' => $expensesData,
    'balance' => $balanceSheet
])->render();

return SimPdf::loadHtml($html)
    ->setPaper('A4', 'landscape')
    ->breakTable(['repeat_header' => true])
    ->setHeader('Financial Statement - Q' . $quarter . ' ' . $year)
    ->setFooter('Prepared by: ' . auth()->user()->name)
    ->addWatermark('DRAFT', ['opacity' => 0.3, 'color' => '#ff0000'])
    ->setMetadata([
        'Title' => 'Financial Statement',
        'Author' => auth()->user()->name,
        'Subject' => 'Quarterly Financial Report'
    ])
    ->download('financial-statement-q' . $quarter . '.pdf');

4. Contract Document

// Perfect for legal documents
$html = view('contracts.agreement', [
    'contract' => $contract,
    'parties' => $parties,
    'terms' => $terms
])->render();

return SimPdf::loadHtml($html)
    ->setPaper('A4', 'portrait')
    ->addPageBreak('page', ['before' => '.contract-section'])
    ->setHeader('Service Agreement - ' . $contract->number)
    ->setFooter('Page {PAGE_NUM} of {PAGE_COUNT} - Legal Document')
    ->addBookmark('Parties', 1)
    ->addBookmark('Terms & Conditions', 1)
    ->addBookmark('Payment Terms', 1)
    ->addBookmark('Signatures', 1)
    ->download('contract-' . $contract->number . '.pdf');

📚 Advanced Usage

Multi-page PDF with Headers and Footers

$html = '
<!DOCTYPE html>
<html>
<head><title>Multi-page Document</title></head>
<body>
    <h1>Page 1</h1>
    <p>Content for page 1...</p>

    <div class="page-break"></div>

    <h1>Page 2</h1>
    <p>Content for page 2...</p>
</body>
</html>';

SimPdf::loadHtml($html)
    ->setPaper('A4', 'portrait')
    ->enablePageNumbers([
        'position' => 'bottom-right',
        'format' => 'Page {PAGE_NUM} of {PAGE_COUNT}'
    ])
    ->setHeader('<h3>Company Header</h3>', [
        'height' => '60px',
        'background' => '#f8f9fa'
    ])
    ->setFooter('<p>© 2026 Company Name</p>', [
        'height' => '40px',
        'background' => '#f8f9fa'
    ])
    ->download('multi-page-document.pdf');

Advanced Table with Custom Breaks

$html = '
<table class="breakable-table">
    <thead>
        <tr>
            <th>Name</th>
            <th>Email</th>
            <th>Department</th>
        </tr>
    </thead>
    <tbody>
        <!-- Large table data -->
    </tbody>
</table>';

SimPdf::loadHtml($html)
    ->setPaper('A4', 'portrait')
    ->breakTable([
        'repeat_header' => true,
        'min_rows' => 5,
        'max_rows' => 20
    ])
    ->addStyle('
        .breakable-table {
            page-break-inside: auto;
        }
        .breakable-table thead {
            display: table-header-group;
        }
        .breakable-table tbody {
            page-break-inside: auto;
        }
        .breakable-table tr {
            page-break-inside: avoid;
        }
    ')
    ->download('table-document.pdf');

Advanced Features

Custom Page Breaks

// Break before specific element
SimPdf::loadHtml($html)
    ->addPageBreak('page', ['before' => '<h2>New Section</h2>'])
    ->download('document.pdf');

// Break after specific element
SimPdf::loadHtml($html)
    ->addPageBreak('page', ['after' => '<div class="section-end"></div>'])
    ->download('document.pdf');

// Avoid breaking inside elements
SimPdf::loadHtml($html)
    ->addPageBreak('avoid', ['element' => '.no-break'])
    ->download('document.pdf');

Watermarks and Bookmarks

SimPdf::loadHtml($html)
    ->addWatermark('CONFIDENTIAL', [
        'opacity' => 0.3,
        'font-size' => '48px',
        'color' => '#ff0000',
        'rotation' => -45,
        'position' => 'center'
    ])
    ->addBookmark('Introduction', 1)
    ->addBookmark('Details', 1)
    ->addBookmark('Summary', 1)
    ->download('document.pdf');

Metadata and Styling

SimPdf::loadHtml($html)
    ->setMetadata([
        'Title' => 'My Document',
        'Author' => 'John Doe',
        'Subject' => 'Important Document',
        'Keywords' => 'PDF, Laravel, Document'
    ])
    ->addStyle('
        body { font-family: Arial, sans-serif; }
        h1 { color: #2c3e50; }
        .highlight { background-color: #ffff00; }
    ')
    ->download('document.pdf');

⚙️ Configuration

The package comes with a comprehensive configuration file at config/simpdf.php. You can customize:

Default paper size and orientation
Font settings and caching
Page break behavior
Header and footer defaults
Page numbering format
Watermark settings
Performance options
Security settings

🏛️ Laravel Integration

Controller Example

<?php

namespace App\Http\Controllers;

use SimPdf\SimPdfLibs\Facades\SimPdf;

class PdfController extends Controller
{
    public function generateReport()
    {
        $html = view('pdf.report', [
            'data' => $this->getReportData()
        ])->render();

        return SimPdf::loadHtml($html)
            ->setPaper('A4', 'portrait')
            ->enablePageNumbers()
            ->setHeader('Report Header')
            ->setFooter('Report Footer')
            ->download('report.pdf');
    }
}

Blade Template

<!DOCTYPE html>
<html>
<head>
    <title>Report</title>
    <style>
        .page-break { page-break-before: always; }
        .no-break { page-break-inside: avoid; }
    </style>
</head>
<body>
    <h1>Report Title</h1>

    @foreach($data as $section)
        <div class="section">
            <h2>{{ $section['title'] }}</h2>
            <p>{{ $section['content'] }}</p>
        </div>

        @if(!$loop->last)
            <div class="page-break"></div>
        @endif
    @endforeach
</body>
</html>

📖 API Reference

Main Methods

loadHtml(string $html) - Load HTML content
setPaper(string $paper, string $orientation) - Set paper size and orientation
setOptions(array $options) - Set PDF generation options
addPageBreak(string $type, array $options) - Add custom page breaks
setHeader(string $content, array $options) - Set header content
setFooter(string $content, array $options) - Set footer content
enablePageNumbers(array $options) - Enable page numbering
addStyle(string $css) - Add custom CSS
addWatermark(string $text, array $options) - Add watermark
addBookmark(string $title, int $level) - Add bookmark
setMetadata(array $metadata) - Set PDF metadata
breakTable(array $options) - Configure table breaking
breakRow(array $options) - Configure row breaking
resetState() - Reset instance state for long-running processes (Octane/Swoole)

Output Methods

output() - Get PDF as raw string bytes
save(string $path) - Save PDF to file (throws PdfGenerationException on failure)
download(string $filename) - Returns Illuminate\Http\Response in Laravel or sends download headers in standalone PHP
stream() - Returns Illuminate\Http\Response in Laravel or streams PDF inline

⚡ Performance & Best Practices

🚀 Performance Tips:

1. Large Documents

// For documents with 100+ pages
SimPdf::loadHtml($html)
    ->setOptions([
        'enable_css_float' => false,  // Disable for better performance
        'enable_html5_parser' => true,
        'dpi' => 72,  // Lower DPI for faster rendering
        'isFontSubsettingEnabled' => true  // Reduce font file size
    ])
    ->download('large-document.pdf');

2. Memory Management

// For memory-intensive operations
ini_set('memory_limit', '512M');
ini_set('max_execution_time', 300);

SimPdf::loadHtml($html)
    ->setOptions(['isPhpEnabled' => false])  // Disable PHP for security
    ->download('document.pdf');

3. Caching Styles

// Cache frequently used styles
$commonStyles = '
    .header { font-size: 14px; font-weight: bold; }
    .footer { font-size: 10px; color: #666; }
    .page-break { page-break-before: always; }
';

SimPdf::loadHtml($html)
    ->addStyle($commonStyles)
    ->download('document.pdf');

🎯 Best Practices:

1. Use Blade Templates

// ✅ Good: Use Blade templates
$html = view('pdf.report', compact('data'))->render();

// ❌ Avoid: Inline HTML in controllers
$html = '<html><body><h1>Report</h1>...</body></html>';

2. Optimize Images

// ✅ Good: Optimize images before PDF generation
$html = '<img src="' . asset('images/optimized-logo.png') . '" width="200">';

// ❌ Avoid: Large unoptimized images
$html = '<img src="' . asset('images/huge-logo.jpg') . '">';

3. Use CSS Classes for Page Breaks

// ✅ Good: Use CSS classes
$html = '<div class="page-break"></div>';

// ❌ Avoid: Inline styles
$html = '<div style="page-break-before: always;"></div>';

4. Handle Errors Gracefully

try {
    return SimPdf::loadHtml($html)->download('document.pdf');
} catch (\SimPdf\SimPdfLibs\Exceptions\PdfGenerationException $e) {
    Log::error('PDF Generation Failed: ' . $e->getMessage());
    return redirect()->back()->with('error', 'Failed to generate PDF: ' . $e->getMessage());
}

📊 Performance Benchmarks:

Document Type	Pages	Size	Generation Time
Simple Report	1-5	< 1MB	< 2 seconds
Business Report	10-20	2-5MB	3-8 seconds
Large Manual	50+	10-20MB	15-30 seconds
Data Export	100+	50MB+	30-60 seconds

📋 Requirements

PHP 8.1 or higher (recommended PHP 8.2+)
Laravel 9.0 or higher (supports Laravel 9, 10, 11, 12)
DomPDF 3.0.1 or higher

📁 Repository File Navigator

Explore all repository components, documentation, source code, and community templates directly:

📄 Documentation & Governance

📜 LICENSE - Official MIT License file
🛡️ SECURITY.md - Security disclosure policy and configuration hardening
🤝 CONTRIBUTING.md - Contribution guidelines, coding standards, and PR process
📜 CODE_OF_CONDUCT.md - Contributor Covenant Code of Conduct
📝 CHANGELOG.md - Version history and release notes
🚀 INSTALLATION.md - Installation methods and framework compatibility
🏗️ PROJECT_STRUCTURE.md - Structural map of package files

⚙️ Configuration

🔧 config/simpdf.php - Full package configuration (fonts, paper size, margins, performance)

💻 Core Source Code (`src/`)

📌 src/SimPdfServiceProvider.php - Service provider with transient container bindings
🎭 src/Facades/SimPdf.php - Laravel Facade accessor
📋 src/Contracts/PdfGeneratorInterface.php - Core contract interface
⚙️ src/Services/PdfGeneratorService.php - Primary PDF generation engine
📑 src/Services/HeaderFooterService.php - Header/footer CSS positioning & margin calculation
📄 src/Services/PageBreakService.php - Page break controls and canvas page numbering
🎨 src/Services/StylingService.php - Watermarks, CSS styling, and bookmarks
🛠️ src/Helpers/PdfHelper.php - Filename sanitization, memory limit calculation, and HTML helpers
🚨 src/Exceptions/PdfGenerationException.php - Package exception definitions

💡 Examples & Resources

📑 examples/laravel-controller-example.php - Complete Laravel Controller implementation
🔌 examples/existing-code-integration.php - Integration with existing Laravel codebases
📘 examples/basic-usage.php - Basic standalone PHP example
📙 examples/advanced-usage.php - Advanced multi-page standalone PHP example
🎨 resources/views/pdf/basic-template.blade.php - Starter Blade PDF template
📊 resources/views/pdf/employee-report.blade.php - Multi-page employee report Blade template

🧪 Testing Suite

🏃 run-tests.php - Custom CLI test runner for fast local testing
🧪 tests/PdfGeneratorTest.php - Complete PHPUnit test suite
🟢 tests/basic-test.php - Basic integration test script
🟡 tests/advanced-test.php - Advanced features test script
🔴 tests/comprehensive-test.php - Comprehensive end-to-end test script

🤖 GitHub Templates (`.github/`)

🔀 .github/PULL_REQUEST_TEMPLATE.md - Standard Pull Request template
🐛 .github/ISSUE_TEMPLATE/bug_report.md - Issue template for bug reports
💡 .github/ISSUE_TEMPLATE/feature_request.md - Issue template for feature requests

🐛 Troubleshooting & Debugging

Common Issues & Solutions:

1. Memory Limit Exceeded

// Solution: Increase memory limit
ini_set('memory_limit', '512M');
ini_set('max_execution_time', 300);

2. Font Not Found

// Solution: Use web-safe fonts or install custom fonts
SimPdf::loadHtml($html)
    ->addStyle('body { font-family: Arial, sans-serif; }')
    ->download('document.pdf');

3. Images Not Displaying

// Solution: Use absolute URLs for images
$html = '<img src="' . asset('images/logo.png') . '" alt="Logo">';

4. Page Breaks Not Working

// Solution: Use proper CSS classes
$html = '<div class="page-break"></div>';

// Add CSS
SimPdf::loadHtml($html)
    ->addStyle('.page-break { page-break-before: always; }')
    ->download('document.pdf');

5. Table Breaking Issues

// Solution: Configure table breaking
SimPdf::loadHtml($html)
    ->breakTable([
        'repeat_header' => true,
        'min_rows' => 5,
        'max_rows' => 20
    ])
    ->download('document.pdf');

🔧 Debug Mode:

// Enable debug mode for troubleshooting
SimPdf::loadHtml($html)
    ->setOptions([
        'debugPng' => true,
        'debugKeepTemp' => true,
        'debugCss' => true
    ])
    ->download('document.pdf');

🧪 Running Tests

To run the complete test suite locally:

# Run integration test runner
php run-tests.php

# Run PHPUnit unit tests
./vendor/bin/phpunit tests/PdfGeneratorTest.php

🤝 Contributing

Contributions are welcome! Please check out our CONTRIBUTING.md and CODE_OF_CONDUCT.md for full guidelines.

Development Setup:

# Clone the repository
git clone https://github.com/5u00n/sim-pdf-libs.git
cd sim-pdf-libs

# Install dependencies
composer install

# Run integration test runner
php run-tests.php

# Run PHPUnit unit tests
./vendor/bin/phpunit tests/PdfGeneratorTest.php

📄 License

This package is open-sourced software licensed under the MIT license.

Made with ❤️ for the Laravel community

sim-pdf / sim-pdf-libs

Maintainers

Package info

Statistics

Security

README

🌟 Features

🚀 Installation

Packagist Installation (Recommended)

Git Installation

🎯 Quick Start

Basic PDF (3 lines using Facade)

Global Helper (simpdf())

Save Directly to Storage Disk (saveToDisk())

Laravel Blade Directives (@pageBreak, @noBreak)

🎯 When to Use SimPDF

✅ Perfect For:

❌ Not Ideal For:

🚀 Best Use Cases:

1. Business Reports

2. Invoice Generation

3. User Manuals

📚 Real-World Usage Examples

1. Employee Report Card

2. Product Catalog

3. Financial Statement

4. Contract Document

📚 Advanced Usage

Multi-page PDF with Headers and Footers

Advanced Table with Custom Breaks

Advanced Features

Custom Page Breaks

Watermarks and Bookmarks

Metadata and Styling

⚙️ Configuration

🏛️ Laravel Integration

Controller Example

Blade Template

📖 API Reference

Main Methods

Output Methods

⚡ Performance & Best Practices

🚀 Performance Tips:

1. Large Documents

2. Memory Management

3. Caching Styles

🎯 Best Practices:

1. Use Blade Templates

2. Optimize Images

3. Use CSS Classes for Page Breaks

4. Handle Errors Gracefully

📊 Performance Benchmarks:

📋 Requirements

📁 Repository File Navigator

📄 Documentation & Governance

⚙️ Configuration

💻 Core Source Code (src/)

💡 Examples & Resources

🧪 Testing Suite

🤖 GitHub Templates (.github/)

🐛 Troubleshooting & Debugging

Common Issues & Solutions:

1. Memory Limit Exceeded

2. Font Not Found

3. Images Not Displaying

4. Page Breaks Not Working

5. Table Breaking Issues

🔧 Debug Mode:

🧪 Running Tests

🤝 Contributing

Development Setup:

📄 License

Global Helper (`simpdf()`)

Save Directly to Storage Disk (`saveToDisk()`)

Laravel Blade Directives (`@pageBreak`, `@noBreak`)

💻 Core Source Code (`src/`)

🤖 GitHub Templates (`.github/`)