manual · pro

Rapls PDF Image Creator Pro Manual

Pro 1.1.0 | Free Rapls PDF Image Creator 1.4.39+ | PHP 7.4+ | WordPress 5.8+

Rapls PDF Image Creator Pro is an add-on for the free Rapls PDF Image Creator. To the thumbnails the free plugin makes, it adds cropping, a page choice per PDF, a queue that keeps going after you close the tab, and replacement detection with a screen for replacing a PDF. On a server that meets two conditions, it can also render PDFs the free plugin cannot, by calling Ghostscript directly.

Resolution, format, quality and the site-wide page number stay on the free plugin’s own settings screen. For those, see the free plugin manual.

01Getting started

Requirements

Installation

1. Install and activate the free Rapls PDF Image Creator (1.4.39 or later) from WordPress.org.
2. Buy Pro on the product page. Your licence key arrives by email.
3. On the download page, enter the email address you bought with and your licence key to get rapls-pdf-image-creator-pro.zip.
4. Go to Plugins → Add New Plugin → Upload Plugin, upload the ZIP and activate it.

Activating the licence

Licence keys look like RPIC-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX.

1. Open Settings → PDF Image Creator Pro → Licence tab.
2. Enter the address you bought with in E-mail and your key in Licence key.
3. Press Activate licence. When it shows “● Licence active” with your email, the masked key and the type (“1 site” or “5 sites”), you’re done.

Messages you may see when activating:

Deactivating and moving sites

A 1-site licence activates on one site, a 5-site licence on up to five. To move to another site, press Deactivate licence on the old site (it asks you to confirm), then activate on the new one. Deactivating frees the slot on the server and removes the key and email from this site.

If the old site is gone or can’t be opened, or a slot stayed taken, write to info@raplsworks.com with the licence key and the old site’s address. This is done at any time, even after the first year of email support. The licence is issued again with a new key, sent by email, and the old key stops working (other sites on the same licence stop at their next daily check until they get the new key). If you only lost your key, the same key is sent to you again.

Where the screens are

02Cropping

Set under “What to crop” and “Fine tuning” on Settings → PDF Image Creator Pro.

What to crop

Fine tuning

Saving shows “Saved. Existing thumbnails are left alone — regenerate the ones you want changed.” Regenerate through the queue or the free plugin’s Bulk Generate tab.

Preview on your own file

1. Under “See it on one of your own files”, pick a PDF from — choose a PDF — (the 20 most recent).
2. Press Render both. Using the settings currently on the screen — including values you haven’t saved — it shows “Without cropping” and “With these settings” side by side.
3. Under the second picture you get the finished size, how much of the page it is, and, if the crop wasn’t applied, why.

03Per-PDF settings

Open a PDF in the Media Library and its edit screen gets these fields. Left empty, or on “Use the site setting”, the site-wide setting applies.

04Direct rendering (Ghostscript)

When a server’s ImageMagick refuses to open PDFs — usually a security policy the host set, sometimes a missing component — the free plugin has no way round it, because the WordPress.org rules it’s published under don’t let it start other programs. Pro isn’t published under those rules, so it can call Ghostscript directly to draw the page and hand the result back to the free plugin to finish.

Requirements

The verdict and its breakdown are under “When this server cannot draw a PDF at all” → “This server” on the settings screen.

The breakdown lists “Starting programs:”, “Ghostscript:” and “Time limit on the renderer:” (yes (this plugin enforces it) / yes (the timeout command) / none — a stuck render cannot be stopped). These answers are remembered for twelve hours; after your host changes something, press Check this server again.

Turning it on

Under “Use it”, tick Fall back to calling Ghostscript directly when the normal path fails and save. It’s off by default, and the box can’t be ticked unless the verdict says it’s available. Turn it on if thumbnails are failing and the free plugin’s Status tab says PDF rendering is blocked or unavailable.

• Once on, the free plugin’s Status tab adds “Thumbnails are being produced by calling Ghostscript directly instead.” and its requirements list gains a “Direct rendering (Pro)” row.
• The queue’s Details column says which renderer drew each thumbnail: “Rendered by calling Ghostscript directly.” or “Rendered by the free plugin.”
• It automatically works around Ghostscript 9.27 and earlier returning pages that use transparency as blank white.

05Refusing oversized pages

Rendering a large page such as A0 at a high resolution can exhaust memory and take the PHP process down with it — no exception, no failure record. While the licence is active, Pro estimates the pixel count from the page size and resolution before drawing, and refuses pages over the limit.

• The limit is the smallest of: 40% of ImageMagick’s area limit, its width and height limits, and 100 megapixels. A4 at 600 dpi and A0 at 150 dpi (about 35 MP) pass; A0 at 300 dpi (about 139 MP) is refused.
• A refused job shows “The page is too large to render at this resolution.” in the queue. Lower the resolution in the free plugin and queue it again.
• There’s no setting for it. If you need a different ceiling, use the rapls_pdfp_max_megapixels filter (in MP; 0 or less removes this ceiling, leaving ImageMagick’s own limits).

// Example: raise the ceiling to 150 MP (a theme's functions.php, for instance)
add_filter('rapls_pdfp_max_megapixels', function () { return 150; });

Measured on Xserver: an A0 page at 600 dpi refused in 0.004 s, where it used to render for 68.5 s.

06The queue

Media → PDF Queue (titled “PDF Thumbnail Queue”). Queued PDFs are processed in the background, and you can close the page. While the page is open it also processes from there and refreshes the counts every few seconds.

Buttons

With more PDFs than one request can queue, you’ll see “There were more PDFs than one request could queue. Carry on from where it stopped:” — press Queue the rest. The result reads “Queued N. Queued again: N. Already waiting: N.” Nothing already queued, or already made with the same settings, is queued twice.

Media Library bulk actions

In Media → Library list view, tick PDFs and choose from “Bulk actions”:

• Queue PDF thumbnails — makes thumbnails for those without one.
• Regenerate PDF thumbnails (queue) — remakes them, replacing existing thumbnails. The list marks these “replaces the existing thumbnail”.

Statuses and retries

Common reasons in the Details column:

Server cron (for quiet sites)

In the background the queue runs on WP-Cron, which only wakes when someone visits the site. On a quiet site that can mean hours. For a steady pace, have the server’s cron call wp-cron.php every five minutes.

*/5 * * * * curl -s https://example.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1

07Replacement detection

A thumbnail is made from a PDF at one moment. If the PDF is replaced later, the thumbnail still shows the old one. Pro watches for that and says so. Watching is always on — it compares file size, time and hash, and changes no image.

What it notices, and what it can’t

Tested with Enable Media Replace 4.2.2, both keeping the file name and renaming it.

Badges and counts

• In Media → Library list view, the “PDF thumbnail” column shows “PDF replaced” (“The thumbnail is of the previous file.”) on replaced PDFs and “Cannot be made” on PDFs that can’t be rendered. A PDF that’s fine shows nothing.
• “Right now” on the settings screen reads “N replaced, N that cannot be made.” with a Queue them for a new thumbnail link when there are replaced PDFs.
• The “This PDF” field on the edit screen says the same.

Remaking automatically

Under “When one is replaced”, ticking Queue a new thumbnail automatically queues each replaced PDF as it’s found. It’s off by default, because it replaces images without being asked. Left off, replaced PDFs are listed and you decide when to remake them (the queue’s “Queue N replaced PDFs”).

08Replacing a PDF

A PDF’s edit screen has a “Replace this PDF” box on the right. It’s deliberately not a row action next to Delete in the Media Library list, where it would be easy to click on the wrong file.

Replacing

1. Open the PDF in the Media Library. “Now” in the box shows the current file name, size and page count.
2. Choose the new PDF.
3. Check Keep the current file name (ticked by default).
4. Press Replace.

Everything that points at this PDF — posts, links, the Media Library entry — keeps pointing at it (the attachment ID doesn’t change). The thumbnail is remade on the spot, and the old thumbnail image isn’t left behind.

Undoing

When a previous file is kept, the box shows “The previous file is kept: name, replaced … ago.” and Put the previous file back. Pressing it asks to confirm, restores the previous file and remakes its thumbnail (“The previous PDF is back under its old name, with a new thumbnail made from it.”).

With keeping set to “none”, the box says “Keeping a copy of the replaced file is switched off in the settings, so a replacement cannot be undone here.”

Kept files and Nginx

Under “Replaced PDFs” → “Replacing one yourself” on the settings screen, Keep this many previous files, so a replacement can be undone: takes none / 1 / 2 / 3 (default 1).

• Kept files go into a folder with an unguessable name under uploads (rapls-pdfp-backups- followed by random characters).
• On Apache, an .htaccess in that folder refuses every request.
• Deleting a PDF from the Media Library deletes its kept files too.

# Nginx example (use the folder name shown on the settings screen)
location ^~ /wp-content/uploads/rapls-pdfp-backups-xxxxxxxxxxxx/ { deny all; }

09Updates

Pro updates come from the Rapls Works update server, not WordPress.org, and arrive in WordPress’s usual update screens. They need an active licence (updates have no time limit; email support from a person is included for a year from purchase, and updates carry on after that).

• Pro’s row on the Plugins screen gets View details and Check for updates. Checking reports “Version N is available. …”, “You have the latest version (N).”, “Updates cannot be checked because the licence is not active.”, or “The update server could not be reached, or did not accept the licence. …” When the last of these appears with an update still offered below it, that offer is the one the server made when it was last reached.
• The licence key never goes in a URL; it’s sent in request headers.
• The ZIP is only accepted over HTTPS, and its size and SHA-256 are checked before installing. If they don’t match you’ll see “The update package failed its integrity check, so it was not installed.” and nothing is replaced.
• Updates still arrive when Pro is switched off because the free plugin is too old — so an update can deliver the fix.

10Uninstalling

Deactivating and deleting Pro on the Plugins screen removes:

Because the kept-files folder is removed, previous PDFs kept for undoing can’t be restored after uninstalling. Put one back first if you need it.

11Troubleshooting

I installed Pro and nothing changed

• Cropping defaults to “Off”. Choose a mode on Settings → PDF Image Creator Pro.
• Existing thumbnails aren’t touched by a settings change. Regenerate with the queue’s “Regenerate all N PDFs”, or select PDFs and use “Regenerate PDF thumbnails (queue)”.
• Check that Settings → PDF Image Creator Pro → Licence tab shows “Licence active”.
• Look for a red notice about the free plugin at the top of the admin.

“Free plugin is missing the extension point”

The free plugin reports a new enough version, but the filter Pro attaches to (rapls_pdf_image_creator_before_resize) isn’t in its code. Reinstall the free plugin from a clean copy. If that doesn’t fix it, contact support and mention that filter name.

The queue isn’t moving

• On a quiet site WP-Cron doesn’t wake. Set up a server cron every five minutes, or keep the queue page open.
• If DISABLE_WP_CRON is true, a server cron is required.
• “Will retry” jobs wait about five minutes.

Thumbnails come out blank

Check the free plugin’s Status tab. For the Ghostscript 9.27-and-earlier transparency bug, both the free plugin and direct rendering apply a workaround. If removing margins gives odd results on a scanned PDF, check Tolerance (avoid 12–21%).

The crop seems to stop partway

Tolerance is most likely in the 12–21% band. Compare the finished sizes in the preview, and move it to 8% or below, or above 21%. To leave one PDF uncropped, set “Cropping” to “Off” on its edit screen.

I replaced a PDF and the old one still downloads

Keeping the file name keeps the URL, so a CDN or browser cache may still return the old PDF. Clear the CDN cache or reload in the browser.

I uploaded a new PDF and there’s no “PDF replaced” badge

Uploading a new PDF and deleting the old one creates a different file, which can’t be detected; the new PDF just gets its own thumbnail. An FTP overwrite shows up on the daily check or with “Check every PDF now”.

The direct rendering checkbox can’t be ticked

“This server” doesn’t say it’s available. Read the reason shown, and after your host changes something press Check this server again.

12FAQ