Pdf To Image Laravel Package

Getting Started

Install the package via Composer: composer require spatie/pdf-to-image. Ensure you have Imagick and Ghostscript installed and configured correctly (critical for PHP CLI and FPM environments—see “Gotchas” below). Start by converting the first page of a PDF to an image:

use Spatie\PdfToImage\Pdf;

$pdf = new Pdf(storage_path('app/pdf/document.pdf'));
$pdf->save(storage_path('app/public/cover.jpg'));

The simplest workflow is chaining method calls to set options before saving—this is the day-to-day pattern you’ll use for most conversions.

Implementation Patterns

• Page selection: Use selectPage(int $number) for single-page exports (e.g., generating cover thumbnails) or selectPages(...$numbers) for batch rendering (e.g., creating page previews for a viewer). Both return the instance for chaining.

$pdf->selectPages(1, 3)->save(storage_path('app/previews'));
// Saves page 1 and 3 as separate images in the directory

• Output control: Standardize previews with size(int $width, ?int $height = null) or thumbnailSize(), adjust DPI/resolution for print-quality assets via resolution(), and enforce format using format(OutputFormat::Webp|Png|Jpeg...).

$pdf
    ->format(OutputFormat::Webp)
    ->size(800, 600)
    ->quality(85)
    ->save(storage_path('app/thumbnails/webp'));

• Bulk processing: Use saveAllPages($directory) for full-document conversion—ideal for archival or document preview generation.

$pdf->saveAllPages(storage_path('app/pages'));
// Outputs page1.jpg, page2.jpg, etc.

• Validation & introspection: Call pageCount() before rendering to skip oversized PDFs, or isValidOutputFormat() for safe dynamic format handling. getSize() returns width/height for responsive layout decisions.

if ($pdf->pageCount() > 100) {
    throw new \RuntimeException('Skipping oversized PDF');
}

• Background handling: backgroundColor() prevents transparent artifacts (especially important for PDFs with transparency layers). Accepts named colors, hex, or rgb() strings.

Gotchas and Tips

• Ghostscript is mandatory: Uncaught ImagickException: FailedToExecuteCommand 'gs' typically means PHP-FPM cannot find gs. Fix by adding env[PATH] = /usr/local/bin:/usr/bin:/bin to php-fpm.conf and restarting the service.

• Security policies block PDF rendering: If you see attempt to perform an operation not allowed by the security policy 'PDF', add <policy domain="coder" rights="read | write" pattern="PDF" /> to /etc/ImageMagick-7/policy.xml (adjust version).

• Ultra-wide PDFs may exhaust resources: Increase width and height limits in policy.xml (e.g., value="4GiB") for large documents—this avoids memory-related Imagick crashes.

• No remote URLs in v3+: Since 3.0, loading from URLs is removed for security. Always use local paths or download first.

• Method name changes in v3: setPage() → selectPage(), setOutputFormat() → format(), getNumberOfPages() → pageCount(). Check the changelog for full migration if upgrading.

• Transparent backgrounds: Versions before 1.2.1 had bugs here—ensure you’re on ≥3.1.0. Use backgroundColor() explicitly if transparency causes unexpected gray/black output.

• Return value ambiguity: save() returns a string for single pages, but an array of paths for multiple pages (e.g., from selectPages() or saveAllPages()). Type-check before consuming.

• Chaining is safe: All setter methods return $this—chain freely, but remember save()/saveAllPages() terminate the chain.

• Performance tip: pingImage() (used internally for pageCount()) avoids full decoding—still, avoid repeated pageCount() calls in tight loops.