README

PDF Transform for Craft CMS 5

PDF Transform is a Craft CMS plugin that transforms a PDF stored in Assets, to an image. This can then be output via Twig in to a template.

A use case for this is to show the preview of a PDF before a user downloads that particular file.

Features

• Transform PDF's to images via Twig (The file needs to be an existing Asset element)
• PDF's are transformed to an image when PDF's are uploaded via Assets or Asset fields.
• Transformed PDF images are indexed and available in Assets like all other asset elements.
• Works with local asset volumes, Amazon S3 and Servd.
• Control where generated images are placed (volume root, subfolder, or mirror source path).
• Restrict auto-transform to specific source volumes.

Install

• Install with Composer via composer require bymayo/pdf-transform from your project directory
• Enable / Install the plugin in the Craft Control Panel under Settings > Plugins
• Customise the plugin settings, especially the Image Volume option.

You can also install the plugin via the Plugin Store in the Craft Admin CP by searching for PDF Transform.

Requirements

• Craft CMS 5.x
• Imagick / Ghostscript
• MySQL (No PostgreSQL support)

Configuration

All settings can be configured from the plugin settings page in the Control Panel, or via a config/pdf-transform.php config file.

Config File

You can override plugin settings by creating a config/pdf-transform.php file in your Craft project:

<?php

return [
    'page' => 1,
    'imageVolume' => null,
    'imageDestination' => 'root',
    'imageSubfolder' => '',
    'imageFormat' => 'jpg',
    'imageResolution' => 72,
    'imageQuality' => 100,
    'cleanFilenames' => false,
    'imageColorspace' => 'srgb',
    'sourceVolumes' => ['*'],
];

This supports Craft's multi-environment config format.

Templating

To transform a PDF to an image use the following Twig tag:

{% set pdfToTransform = entry.pdfAsset.one() %}

{% set transformedPdf = craft.pdfTransform.render(pdfToTransform) %}

{{ transformedPdf.url }}

The transformed PDF (Now an image stored in Assets) can then be output using {{ transformedPdf.url }}. Or get any Asset property e.g. title, id, filename etc.

If the transformed image doesn't exist then the PDF will be transformed via the template. This may cause the template/page to become slow whilst the PDF is transformed.

Be aware that this also may output a large image, so we'd recommend running this through an image transform. See Dimensions.

Known Issues

Imagick / Ghostscript

The plugin runs PDFs through a PDF library called pdf-to-image. They have known issues with Imagick where transforms may fail if Ghost Script isn't accessible through Imagick (Very easily resolvable)

Read more about this issue - https://github.com/spatie/pdf-to-image#issues-regarding-ghostscript.

Dimensions

PDF Transform does the basic job of converting your PDF to a single image. It will never be it's role to set width and height dimensions (Other than Image Resolution).

I'd recommend running the PDF image through one of the following options/plugins and setting the dimensions that way (Some of these also handle caching the image as well)

• Image Transforms by Craft
• Imager X by aelvan
• Image Optimize by nystudio107

Support

If you have any issues (Surely not!) then I'll aim to reply to these as soon as possible. If it's a site-breaking-oh-no-what-has-happened moment, then hit me up on the Craft CMS Discord - @bymayo