Media PDF Thumbnail
Generates thumbnail images from PDF files for Media entities using ImageMagick and displays them as field formatters.
media_pdf_thumbnail
Install
composer require 'drupal/media_pdf_thumbnail:^6.1'
Overview
The Media PDF Thumbnail module generates a thumbnail image from PDF files and allows it to be used as the thumbnail for Media entities. When a Media entity contains a PDF file, this module can automatically generate an image from a specific page of the PDF and display it instead of the default thumbnail.
The module uses ImageMagick (via PHP's Imagick extension) and the spatie/pdf-to-image library to perform the PDF to image conversion. Generated images are stored in a custom entity type (pdf_image_entity) that tracks the relationship between the source PDF and the generated image.
Key capabilities include support for multi-page PDFs (selecting which page to use), choice of output format (JPG or PNG), configurable destination paths for generated images, and both synchronous and asynchronous (cron-based) image generation. The module integrates with Drupal's token system for programmatic access and provides hooks for customization.
Features
- Generates thumbnail images from PDF files using ImageMagick and spatie/pdf-to-image library
- Multi-page PDF support - specify which page to extract the thumbnail from (default is page 1)
- Supports JPG and PNG image output formats
- Field formatter (Media PDF Thumbnail Image) for the thumbnail field of Media entities
- Synchronous (on-the-fly) or asynchronous (cron queue) image generation modes
- Custom entity type (pdf_image_entity) for storing PDF-to-image mappings with revision and language support
- Configurable destination paths for public and private file storage
- Views integration for managing PDF image entities with filters and bulk operations
- Token system integration for programmatic access to generated images and renders
- Private file access control with dedicated permission for viewing private thumbnails
- Alter hooks for customizing image rendering and destination paths
- Image link options: link to content, link to generated image file, or link to original PDF file
- HTML attribute configuration for links (download, target, rel)
- Batch operations for queue processing and entity purging
- Automatic cache invalidation when thumbnails are generated
- Support for remote file storage (S3, etc.) with automatic temporary file handling
Use Cases
Document Library with PDF Previews
Create a document library Media type for storing PDF documents. Configure the Media PDF Thumbnail formatter on the thumbnail field to automatically generate preview images from the first page of each uploaded PDF. Users can see visual previews of documents without downloading them, improving the browsing experience.
Magazine or Publication Archive
For a digital magazine archive, configure the formatter to extract thumbnails from specific pages (e.g., cover page). Link the thumbnail image directly to the PDF file for easy download. Use the 'download' attribute so clicking opens a download dialog instead of navigating away.
Multi-page Document Thumbnails
For multi-page documents where the first page is a cover sheet, configure the formatter to use page 2 or another significant page for the thumbnail. This ensures the preview shows meaningful content rather than a generic title page.
Private Document Repository
For sensitive documents stored in the private file system, configure private destination URIs for thumbnails. Grant the 'view private pdf thumbnails' permission only to authenticated users who should access the documents. Thumbnails remain protected alongside the source PDFs.
High-Volume PDF Processing
For sites with many PDF uploads, enable the 'Use cron' option on the formatter. This queues thumbnail generation for background processing, preventing slow page loads during media upload or initial viewing. Monitor the queue admin page to ensure processing keeps up with uploads.
Programmatic Thumbnail Access via Tokens
Use the token system to access generated thumbnails in custom code, Views, or Rules. Examples: [media_pdf_thumbnail:field_media_file:1:jpg:image_uri] returns the file URI, [media_pdf_thumbnail:field_media_file:1:jpg:render:medium] returns rendered HTML with an image style.
Tips
- Use cron-based generation for better performance on high-traffic sites - thumbnails are generated in the background
- Clear caches after changing formatter settings for changes to take effect on existing content
- The 'Clean' function at /admin/media-pdf-thumbnail/settings/purge can regenerate all thumbnails by deleting entities - thumbnails will be recreated on next view
- For multi-language sites, thumbnails are generated per language and revision
- Use the token system for programmatic access: [media_pdf_thumbnail:field_name:page:format:image_uri]
- Configure image styles on the formatter for consistent sizing and to reduce bandwidth
- The 'Link image to PDF File' option is convenient for document download functionality
Technical Details
Admin Pages 4
/admin/media-pdf-thumbnail/settings/list
Displays a Views-based list of all PDF image entities created by the module. This table shows the relationship between source entities and their generated thumbnails, including entity type, bundle, entity ID, revision ID, language, PDF field name, PDF file ID and URI, page number, generated image file ID and URI, image format, and timestamp. The view includes exposed filters for entity type, bundle, language, entity ID, and date. Each row has delete operation links for individual entity management.
/admin/media-pdf-thumbnail/settings/global
Configure global settings for PDF thumbnail generation, including custom destination paths for generated images.
/admin/media-pdf-thumbnail/settings/queue
Manage the PDF image generation queue. When using cron-based generation, thumbnails are added to a queue and processed during cron runs. This page allows you to view the queue status and manually trigger processing.
/admin/media-pdf-thumbnail/settings/purge
Delete all PDF image entities and their associated image files. This is a destructive operation that removes all generated thumbnails from the system.
Permissions 8
Hooks 2
hook_media_pdf_thumbnail_image_render_alter
Allows modules to alter the rendered PDF thumbnail image element before display. Useful for modifying alt text, title, or other image attributes.
hook_media_pdf_thumbnail_image_destination_alter
Allows modules to alter the source and destination paths for PDF image generation. Useful for customizing where thumbnails are stored.
Troubleshooting 6
Check that the Imagick PHP extension is installed and enabled. Verify ImageMagick is installed on the server (version 6.3.7+). Check the Drupal logs for error messages from 'Media PDF Thumbnail' logger channel. Ensure the destination directory is writable.
Ensure cron is running regularly. Check the Queue admin page at /admin/media-pdf-thumbnail/settings/queue. Use the 'Run' button to manually process the queue. Verify no errors are occurring during processing by checking the logs.
Grant the 'view private pdf thumbnails' permission to the appropriate user roles. Verify the private file system is properly configured in Drupal settings.
The PDF file may be invalid, corrupted, or the Imagick extension cannot process it. Check that the file field actually contains a PDF (MIME type application/pdf). Review error logs for specific ImageMagick errors.
ImageMagick version must be 6.3.7 or higher. spatie/pdf-to-image library must be version 2.1.0 or higher. Run 'composer require spatie/pdf-to-image:^2.1.0' to update if needed.
The module supports remote storage by copying PDFs to temporary local storage for processing. If issues occur, check that the temporary:// stream wrapper is properly configured and has sufficient space.
Security Notes 4
- The 'administer_media_pdf_thumbnail' permission should only be granted to trusted administrators as it allows purging all thumbnail data
- The 'view private pdf thumbnails' permission controls access to thumbnails generated from private files - review carefully before granting
- Generated thumbnails inherit the file system location (public/private) of the source PDF unless custom destination URIs are configured
- The module implements hook_file_download() to enforce permission checks on private thumbnails