Efficiently Rendering Base64 Images in Laravel PDFs with DomPDF

When generating PDFs in Laravel using DomPDF, handling images can be tricky. One common challenge is memory consumption, especially when dealing with multiple images in a single PDF. In this post, I'll share a robust solution for embedding images in Laravel PDFs while managing memory efficiently.

The Challenge

DomPDF requires images to be embedded directly in the HTML as base64-encoded strings. However, loading multiple images into memory simultaneously can quickly exceed PHP's memory limits, particularly when generating large catalogues or reports.

The Solution

I've developed a memory-efficient approach that:

Processes images in chunks to prevent memory overflow
Handles missing images gracefully
Supports both local and remote image files
Uses base64 encoding for DomPDF compatibility

Here's the complete solution:

@php
ini_set('memory_limit', '256M');

function processImage($imagePath) {
    if (!file_exists($imagePath)) {
        // Return a 1-pixel transparent image as fallback
        return 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=';
    }

    // Read file in chunks to avoid memory issues
    $handle = fopen($imagePath, 'rb');
    $contents = '';
    while (!feof($handle)) {
        $contents .= fread($handle, 8192); // Read 8KB at a time
        }
    fclose($handle);

    return base64_encode($contents);
}
@endphp

How It Works

Let's break down the key components:

1. Memory Management

ini_set('memory_limit', '256M');

We start by setting a reasonable memory limit. 256MB is usually sufficient for most PDF generation tasks while preventing runaway memory usage.

2. Chunk-based File Reading

$handle = fopen($imagePath, 'rb');
$contents = '';
while (!feof($handle)) {
    $contents .= fread($handle, 8192);
}

Instead of loading the entire image into memory at once using file_get_contents(), we:

Open the file in binary read mode
Read it in 8KB chunks
Concatenate the chunks until we reach the end of file
Close the file handle properly

This approach significantly reduces memory usage when processing large images.

3. Fallback for Missing Images

if (!file_exists($imagePath)) {
    return 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=';
}

If an image file is missing, we return a base64-encoded 1x1 transparent PNG instead of throwing an error. This ensures your PDF generation won't fail due to missing images.

Usage in Blade Templates

Here's how to implement this solution in your Blade template:

<div>
    @php
    $imagePath = $item['image_url'];
    if (empty($item['image_url'])) {
        $imagePath = public_path('images/placeholder.jpg');
    }
    $base64Image = processImage($imagePath);
    @endphp
    <img src="data:image/png;base64,{{ $base64Image }}" alt="">
</div>

The template:

Checks for an image URL
Falls back to a placeholder if none exists
Processes the image through our memory-efficient function
Embeds the base64-encoded result in an img tag

The $item['image_url'] holds the full absolute path of the image something like /var/www/html/....

Styling Considerations

To ensure your images display correctly in the PDF, consider these CSS properties:

.item-image img {
    object-fit: cover;
    object-position: center;
    border-radius: 0.375rem;
    max-width: 100%;
    height: auto;
}

This ensures images:

Maintain their aspect ratio
Don't overflow their containers
Have consistent styling

Benefits

This solution offers several advantages:

Memory Efficiency: By reading files in chunks, we avoid memory spikes
Reliability: Graceful handling of missing images prevents PDF generation failures
Flexibility: Works with both local and remote image files
Compatibility: Base64 encoding ensures images work correctly with DomPDF
Scalability: Can handle multiple images in a single PDF document

Conclusion

Generating PDFs with images in Laravel doesn't have to be a memory-intensive process. By implementing chunk-based file reading and proper error handling, you can create robust PDF generation systems that work reliably at scale.

Remember to adjust the memory limit and chunk size based on your specific needs and server constraints. Monitor your application's memory usage in production to ensure optimal performance.

This solution is particularly useful for generating auction catalogs, product listings, or any other PDF documents that require multiple images while maintaining performance and reliability.

Blog