Rapls PDF Image Creator Manual (Free)

How to use the free plugin that turns a PDF’s cover into an image and sets it as the featured image.
Version 1.4.45 | WordPress 5.0+ | PHP 7.4+

01About the plugin

When you upload a PDF to the Media Library, the plugin converts a page of it into an image and sets that image as the PDF’s featured image. The conversion uses the PHP Imagick extension (ImageMagick).

• Automatic: the thumbnail is made at upload.
• Every size: full size plus every image size your theme registers.
• No blank saves: a page that is one flat colour counts as a failed render and is not saved.
• Colour management: CMYK PDFs are converted to sRGB through ICC profiles.
• A reason: when it can’t make a thumbnail, the Status tab and Site Health say why and what to do.
• No processes: it never uses exec() or anything like it, so it works on locked-down shared hosting.

02Requirements

Most shared hosts qualify. After installing, the Status tab tells you whether yours does.

03Installation

1. In the dashboard, open Plugins → Add New and search for “Rapls PDF Image Creator”.
2. Click Install Now, then Activate.
3. Open Settings → Rapls PDF Image Creator and check the requirements on the Status tab.
4. Upload one PDF and confirm a thumbnail appears.

The settings screen has three tabs: Settings, Bulk Generate and Status.

04Check the Status tab

Settings → Rapls PDF Image Creator → Status. “Server Status” shows whether this server can render PDFs. The answers come from reading PDFs built in memory, not from version numbers.

Status tab

Results are remembered for twelve hours. After your host changes something, click Check this server again.

Statistics at the bottom shows “Total PDFs”, “With thumbnail” and “Without thumbnail”; Refresh Statistics counts again.

If the last thumbnail could not be made, the reason is shown here with when it happened. It clears itself the next time a thumbnail is generated successfully.

05The Settings tab

Settings → Rapls PDF Image Creator → Settings

Image Settings

Behavior Settings

Display Settings

Insert Settings

What gets output when a PDF is inserted from the post editor.

<a href="%PDF_URL%" target="_blank">
  <img src="%THUMBNAIL_URL%" alt="%TITLE%">
</a>

The output goes through wp_kses_post(), so anything not allowed in post content is stripped.

06Bulk Generate

For PDFs uploaded before the plugin was installed, or thumbnails you want to remake after changing settings.

Settings → Rapls PDF Image Creator → Bulk Generate

1. To remake existing thumbnails, tick Include PDFs that already have thumbnails (regenerate).
2. Click Scan for PDFs. “Scan Results” shows how many were found.
3. Click Start Generation. “Progress” counts Generated and Failed; “Log” lists each result.
4. Click Stop to stop part way.

When nothing is found, the screen says why (no PDFs in the library, or every PDF already has a thumbnail). In the second case it offers a button to scan again including them.

07Media Library

• Covers: in grid and list view, the generated thumbnail replaces the PDF icon (when Display Thumbnail Icon is on).
• Edit Media screen: a PDF with a generated thumbnail shows that thumbnail in the Edit Media preview too (since 1.4.3).
• PDFs in image pickers: a PDF with a thumbnail is offered in WordPress’s own image pickers only: the Image, Gallery and Post Featured Image blocks, the block editor’s featured image, and the classic editor’s “Set featured image” and the featured image view of “Add Media”. It is not offered in other plugins’ pickers, or in core pickers such as Cover and Media & Text. Returning true from the filter rapls_pdf_image_creator_pdfs_in_every_image_picker offers PDFs in every picker that asks for images, as up to 1.4.20. A PDF dropped or pasted into the block editor becomes a File block, not an Image block; to show a PDF as an image, choose it in the Image block’s Media Library tab.
• “PDF Thumbnail” column: the list view gets a column showing whether each PDF has a thumbnail (✓ / ✗).
• Row links: hover a PDF’s row for Generate Thumbnail (when it has none) or Regenerate Thumbnail, to remake just that one.

Media → Library (list view)

Generated files

Uploading my-document.pdf produces files like these (sizes depend on your theme):

my-document-pdf.jpg            full size
my-document-pdf-1024x768.jpg   large
my-document-pdf-300x225.jpg    medium
my-document-pdf-150x150.jpg    thumbnail

A regenerated thumbnail gets a different filename from the one before, because with the same URL browsers keep showing the old image.

08Inserting into posts

When you choose a PDF through “Add Media” in the post editor and insert it, the output follows Insert Settings.

When you want finer control over where the thumbnail goes in a post, the shortcodes in the next section work too.

09Shortcodes

id is the PDF’s attachment ID — the number after item= or post= in the URL when you open the PDF in the Media Library. Since 1.4.45 the shortcodes take a PDF’s ID only. To bring back 1.4.20’s behaviour, where any post’s ID could be given, return true from the filter rapls_pdf_image_creator_shortcode_any_post; it is still shown only to a reader who may see that post.

[rapls_pdf_clickable_thumbnail id="123" size="medium"]
[rapls_pdf_download_link id="123" text="Download the brochure" show_thumbnail="false"]

10Template functions

$pdf_id = 123;
if ( rapls_pic_has_thumbnail( $pdf_id ) ) {
    echo rapls_pic_get_thumbnail_image( $pdf_id, 'medium' );
}

Listing every PDF attached to a post:

$pdfs = get_posts( array(
    'post_type'      => 'attachment',
    'post_mime_type' => 'application/pdf',
    'post_parent'    => get_the_ID(),
    'posts_per_page' => -1,
) );

foreach ( $pdfs as $pdf ) {
    if ( rapls_pic_has_thumbnail( $pdf->ID ) ) {
        printf(
            '<a href="%s">%s</a>',
            esc_url( wp_get_attachment_url( $pdf->ID ) ),
            rapls_pic_get_thumbnail_image( $pdf->ID, 'thumbnail' )
        );
    }
}

11When no thumbnail appears

Start with Tools → Site Health, “PDF thumbnail generation”, or the Status tab. Who to ask, and what to ask for, depends on the cause.

The server can’t read PDFs

Only this PDF fails

Blank thumbnails

Since 1.4.0 a page that is one flat colour is not saved: the PDF keeps its icon and the Status tab says why. There are two usual causes.

• An old Ghostscript (9.27 or earlier): it fails on an image inside a transparency group and returns a white page without an error — typically with PowerPoint and Illustrator exports. Since 1.4.1 the page is read once more with an instruction to switch transparency off (GS_OPTIONS) placed in the environment for that one read. A page that already rendered is never touched. The lasting fix is for your host to update Ghostscript.
• Some ImageMagick 6 builds with CMYK PDFs: some builds take CMYK PDFs from Ghostscript in a format (bmpsep8) ImageMagick itself can’t decode. The plugin can’t work around it. Ask your host to upgrade to ImageMagick 7, or to change the ps:cmyk delegate in delegates.xml from bmpsep8 to pamcmyk32. RGB PDFs are unaffected, so suspect this when only some PDFs come out white.

Colours too vivid

Without a CMYK ICC profile on the server, conversion falls back to arithmetic that exaggerates greens and blues. Check “Color Management” on the Status tab. Installing a CMYK profile on the server, or pointing the rapls_pdf_image_creator_icc_paths filter at one, restores accurate colour.

Thumbnails made before an update keep their old colours; regenerate them with Bulk Generate. To keep the previous colours instead:

add_filter( 'rapls_pdf_image_creator_color_conversion', function() {
    return 'naive';
} );

12Filters and actions

Using page two as the cover (the Page Number setting does the same):

add_filter( 'rapls_pdf_image_creator_thumbnail_page', function( $page, $pdf_id ) {
    return 1; // 0-indexed, so page two
}, 10, 2 );

13Uninstalling

Deleting the plugin removes its settings and the thumbnail images it generated. To keep the images, turn on Display Settings → Keep Images on Uninstall before deleting; they stay in the Media Library as ordinary images. Your PDF files themselves are never deleted.

14FAQ

Can I use a page other than the first?

Yes. Set the site-wide page in Page Number on the Settings tab (0 is the first page). The “Page Selection” row on the Status tab shows whether choosing a page works on your server.

I updated and the thumbnails still have the old colours.

Updates don’t regenerate thumbnails. Run Bulk Generate with “Include PDFs that already have thumbnails (regenerate)” ticked.

I regenerated, but the screen still shows the old image.

Since 1.4.1 a regenerated image gets a new filename, so browser caches don’t get in the way. For images made before that, clear your browser cache and look again.

Only the Edit Media screen shows a blank white preview.

That is how 1.4.2 and earlier behaved. WordPress draws its own preview of every PDF at upload, without this plugin’s workaround for pages that come back white, and the Edit Media screen showed that preview. Since 1.4.3 a PDF with a generated thumbnail shows the thumbnail there instead. Updating the plugin fixes it; the thumbnails do not need regenerating.

Does it run commands on the server?

No. PDFs are drawn by ImageMagick through the Imagick extension, and the plugin starts no processes. The blank-page retry only places an environment variable for the length of one read.

15About the add-on

There is a paid add-on for this free plugin, Rapls PDF Image Creator Pro. It adds a page choice and crop per PDF, detection of replaced PDFs with a screen for replacing them, and a queue that keeps going after you close the tab. The free plugin behaves the same whether it is installed or not. The plugin mentions the add-on in five places only: its row on the Plugins screen, a card at the bottom of the Settings tab, the Status tab, and once under the page-number field after you change it. Returning false from the filter rapls_pdf_image_creator_show_upsell removes all of them.