Skip to main content
Version: 2026.3

Asset Document Thumbnails (PDF, DOCX, ODF, ...)

This feature creates image thumbnails from nearly any document format, including DOC(X), PPT(X), PDF, XLS(X), ODT, ODS, ODP, and many others.

You can use existing image thumbnail configurations to create a thumbnail of your choice.

Required Tools​

This feature requires Ghostscript, which renders the page image and counts the pages of the document. Non-PDF formats (DOC(X), PPT(X), XLS(X), ODT, ODS, ODP, ...) additionally require Gotenberg or LibreOffice to convert the document to PDF first.

pdftotext is only relevant for the process_text option (see Configuration below), which extracts text for search indexing. It is optional, since Ghostscript can also extract text via its txtwrite device, though less accurately.

See Optional System Dependencies for a full overview of these tools and how to configure their binary locations.

Important Thumbnail processing for documents runs asynchronously as part of the Symfony Messenger queue, under the pimcore_asset_update messenger queue.

Examples​

$asset = Asset::getById(123);
if($asset instanceof Asset\Document) {

// get a thumbnail of the first page, resized to the configuration of "myThumbnail"
echo $asset->getImageThumbnail("myThumbnail");


// get the thumbnail for the second page (1-based) using a dynamic configuration
echo $asset->getImageThumbnail(["width" => 230, "contain" => true], 2);


// get the thumbnail URL for all pages, but do not generate them immediately (see third parameter)
// the thumbnails are then generated on request
$thumbnailUrls = [];
for($i=1; $i<=$asset->getPageCount(); $i++) {
$thumbnailUrls[] = $asset->getImageThumbnail("myThumbnail", $i, true);
}

}

Building Thumbnails for a List of Assets​

It is recommended to use named thumbnails for caching purposes.

$list = new Asset\Listing();
$assets = $list->getAssets();
foreach ($assets as $asset) {
echo match (true) {
$asset instanceof Asset\Image => $asset->getThumbnail('myThumbnail')?->getPath(),
$asset instanceof Asset\Document => $asset->getImageThumbnail('myThumbnail')?->getPath(),
default => '',
};
}

Configuration​

Asset documents depend on background processes to generate thumbnails and extract search text. These processes require page count processing, which can consume unnecessary resources if the feature is not used.

You can disable or fine-tune these background processes:

pimcore:
assets:
document:
thumbnails:
enabled: true # process thumbnails for asset documents (default: true)
process_page_count: true # process & store page count, required for thumbnails & text generation (default: true)
process_text: true # process text for asset documents, used by search (default: true)
scan_pdf: true # scan PDF documents for unsafe JavaScript (default: true)
open_pdf_in_new_tab: only-unsafe # 'all-pdfs' | 'only-unsafe' | 'none' (default: only-unsafe)
OptionDefaultDescription
thumbnails.enabledtrueProcess thumbnails for asset documents.
process_page_counttrueProcess and store page count. Internally required for thumbnails and text generation.
process_texttrueExtract text from asset documents (used by search), via pdftotext or, as a fallback, Ghostscript.
scan_pdftrueScan PDF documents for unsafe JavaScript.
open_pdf_in_new_tabonly-unsafeControls PDF display: all-pdfs (show thumbnail for all PDFs), only-unsafe (show thumbnail only for PDFs with JavaScript), none (show all PDFs inline, not recommended).