Weave Code
Pdf To Image Laravel Package
spatie/pdf-to-image
Convert PDF pages to images with this simple PHP class built on Imagick and Ghostscript. Save as jpg, jpeg, png, or webp, render any page, and check page counts. Requires PHP 8.2+.
spatie/pdf-to-image is a lightweight PHP package for converting PDF documents into one or more images using Imagick and Ghostscript. It provides a simple API: instantiate Pdf with a file path and call save() to render the first page, with automatic format detection from the target extension.
- Supports JPG, JPEG, PNG, and WebP output; defaults to JPG.
- Select specific pages with
selectPage()and count pages viapageCount(). - Validate output formats using
isValidOutputFormat(). - Returns a string for one image or an array for multiple images.
- Requires PHP 8.2+, Imagick, and Ghostscript.
Frequently asked questions about Pdf To Image
- How do I install spatie/pdf-to-image and what does it require?
- Install it with composer require spatie/pdf-to-image on PHP 8.2 or newer. You also need the Imagick PHP extension compiled and installed, plus the Ghostscript gs binary available on the machine that runs the conversion. There is no service provider, facade, config file, or migration to publish, so installation really is just Composer plus those two system dependencies.
- Is spatie/pdf-to-image a Laravel package, and does it support Laravel 10 and 11?
- It is a framework-agnostic PHP class rather than a Laravel package: there is no service provider, facade, or config file to register. That means it works inside any Laravel version whose runtime is PHP 8.2+, including Laravel 10 and 11, and you simply instantiate new Spatie\PdfToImage\Pdf($path) where you need it. If you want it injectable, bind it in your own service provider or wrap it in a small service class.
- Why am I getting FailedToExecuteCommand 'gs' when converting a PDF?
- That error means Ghostscript is not reachable from the user running PHP, which is a very common problem when the CLI has gs on PATH but PHP-FPM does not. Fix it by setting env[PATH] in php-fpm.conf to include the directory containing the gs binary, then restart the pool. Verify by running gs --version as the same system user your application uses, since a CLI check alone will not catch this.
- How do I convert only one page or a specific range of pages from a PDF?
- By default only the first page is rendered, so call selectPage() with a page number or selectPages() with several page numbers before saving. When more than one page is rendered, save() returns an array of file paths instead of a single string, so type-check the return value in your code. Use saveAllPages() if you want every page in the document rasterized.
- How can I get the total number of pages in a PDF with this package?
- Call pageCount() on the Pdf instance, which returns an integer. This is useful for validating uploads, capping how many pages you are willing to rasterize, or deciding how to chunk a large document across queue jobs. It reads the document's page count, so it is cheap compared with actually rendering every page.
- Can spatie/pdf-to-image save images as PNG or WebP instead of JPG?
- Yes. The output format is inferred from the extension of the path you pass to save(), and jpg, jpeg, png, and webp are supported; anything else falls back to jpg. You can check a format ahead of time with isValidOutputFormat('webp'). Choose the format deliberately, since webp and png files behave differently in browsers and downstream image pipelines.
- Does spatie/pdf-to-image extract text from PDFs or perform OCR?
- No, the package only rasterizes pages into images using Imagick and Ghostscript, so there is no text extraction, OCR, or searchable output. If you need searchable content or thumbnails with text, you will need a second component such as a PDF text parser or an OCR service. In that case it is worth evaluating whether a single tool that both rasterizes and extracts text is a better fit than combining two libraries.
- Is it safe to convert user-uploaded PDFs with spatie/pdf-to-image?
- Treat PDF parsing as a hostile-input surface, because Ghostscript has a history of remote code execution class vulnerabilities and the package itself imposes no sandboxing. For untrusted uploads you should isolate conversion in a container or dedicated worker where a compromise cannot reach your application secrets or database. That also means tracking Ghostscript and ImageMagick CVEs and rebuilding the image on a regular cadence, not just running composer update.
- Should PDF to image conversion run in a Laravel queue job, and how do I stop it exhausting resources?
- Always run it in a queued job rather than in the request cycle, since rasterizing takes seconds per page at high DPI and can time out a web request. The package ships no limits, so you must cap input file size, page count, DPI, and output dimensions yourself before calling save(). Also check ImageMagick's policy.xml on the worker image: the PDF coder must be permitted, and width, height, memory, and disk limits need to be raised deliberately for wide-format documents.
- What changed in spatie/pdf-to-image v3 and how hard is the upgrade from v2?
- Version 3 requires PHP 8.2+ and renamed most of the fluent methods, so a v2 to v3 migration touches your code rather than being a plain composer update. URL loading was also dropped in v3, so if you currently pass remote PDF URLs you need to download the file first. Stay on v2 only for legacy runtimes and budget explicit migration time, because major-version churn here is a real maintenance consideration.
Weaver
How can I help you explore Laravel packages today?