uiii / processwire-fieldtypepdf

Fieldtype/Inputfield module for ProcessWire allowing easy generation of thumbnails of the PDF files

PDF Fieldtype/Inputfield

Module for ProcessWire CMS allowing you to easily generate images from the PDF files embedded to the site.

1. Requirements
2. Installation
3. How to use
   • In site's administration
   • In templates
4. API documentation
5. Tests
6. Upgrading from 1.0.1 and lower
7. Troubleshooting
8. Changelog

Requirements

• Processwire 3+
• ImageMagick PHP extension
• Ghostscript

For ProcessWire 2.x support use version 1.x, maintained in pw-2 branch.

Installation

How to install or uninstall modules.

Via Composer

In your ProcessWire installation root run:

composer require uiii/processwire-fieldtypepdf

Login to your ProcessWire admin and go to Modules > Refresh and install the module.

If you want to read more about ProcessWire and Composer visit https://processwire.com/blog/posts/composer-google-calendars-and-processwire/

How to use

In site's administration

Add a field and set its type to PDF. Use the field the same way as the file field (obviously, this accepts only *.pdf files). After the file is uploaded you will see a small thumbnail of it, just like for image field.

Image generation is highly configurable (image format, extension, background, ...). See the PDF to image converter section on field's Details tab.

In templates

There are some backward-compatible API changes against the version 1.0.1 and lower, see Upgrading from 1.0.1 and lower.

The PDF field extends file field and adds new hookable ___toImage($page = 0, $options = array()) method to generate the image from PDF.

$image = $page->pdfFile->toImage();
$image->size(100, 100);

Method accepts two optional parameters. First is the $page, which specifies the PDF's page number the image is generated from, default is 0. The exception is thrown if the page is out of range.

The second is $options parameter, which is an array of options to override the options set in administration.

$options = array(
	'suffix' => array('suffix1', 'suffix2'), // suffixes used in filename
	'forceNew' => false, // if TRUE the image is regenerated if already exists
	'format' => 'JPEG', // image format
	'extension' => 'jpg', // image file extension
	'background' => '#FFFFFF', // background color used when the PDF has transparent background
	'resolution' => '300x300', // resolution used when reading the PDF
	'colorspace' => Imagick::COLORSPACE_RGB, // colorspace used when reading the PDF
	'imagickOptions' => array( // ImageMagick options
		'pdf:use-cropbox=true'
	)
)

For each combinations of page and suffixes there will be one image. The generated images are saved in page's assets and will be created only once until forceNew options is TRUE. The image is the instance of Pageimage, so you can do with it whatever you can do with the image field. When you delete the PDF file the generated images are deleted too.

API documentation

Generate into doc directory:

apigen generate -d doc

Tests

DO NOT run the tests against the production site. They modify the fields, templates and pages as they need, so can potentially damage your site!

Prepare the PW testing installation and export the PW_PATH environment variable containing the path to the root of that installation. Copy the module sources in the $PW_PATH/site/modules/FieldtypePDF directory.

Install required packages:

composer install

Run the tests

./vendor/bin/phpunit

Test multiple ProcessWire versions (automatically)

You can also automatically test against multiple ProcessWire versions. It uses Tense tool for it.

1. Install reuquired packages:

   composer install
   

2. Run the tests:

   vendor/bin/tense run
   

WARNING: The tool will ask you for database connection parameters. Configure the db connection parameters carefully because it creates and drops a database for each ProcessWire installation.

Upgrading from 1.0.1 and lower

In 1.1.0 some methods of class PagePDF are deprecated. See the list here. You doesn't have to make any changes but it is recommended to use the new API, for compatibility with later versions.

Instructions for replacing the deprecated methods:

• $page->pdf->thumbnail($width, $height) replace with the code

$image = $page->pdf->toImage();
$image->size($width, $height);

• isThumbnail($basename) replace with isImageOfThis($basename)

NOTE: There is certain incompatibility between these two methods. While isThumbnail returns TRUE for all the images generated from the PDF and also theirs derivatives (e.g. pdf.jpg, pdf.100x100.jpg), the isImageOfThis return TRUE only for the images generated directly from PDF (e.g. pdf.jpg). That doesn't change much, because you can use it in combination with Pageimage::isVariation.

• removeThumbnails replace with removeImages

Troubleshooting

Thumbnail's colors do not match the colors in PDF

To fix that, you need to made some changes in ImageMagick delegate files. Detailed instructions can be found here: http://www.lassosoft.com/CMYK-Colour-Matching-with-ImageMagick

GhostScript exceptions occured

If you got some GhostScript exceptions when generating image, update GhostScript and ImageMagick to the latest versions.

If you can't, you can use the fallback mode. Turn it on in the module's settings.

Be aware of that this will produce low quality images and most of the field type options won't be abvailable.

processwire-fieldtypepdf's Issues

ImageMagick settings

Set proper settings to ImageMagick before conversion:

$imagick->setOption("pdf:use-cropbox","true");
$imagick->setColorspace(Imagick::COLORSPACE_RGB);

https://processwire.com/talk/topic/6426-pdf-fieldtypeinputfield/?p=62918

add Travis CI

Does not work in ProcessWire 3.x

Version 1.0.1 and 1.1.0 both have massive problems. Is this module still under development? Would be great to use for future projects!

ProcessWire 3.0.32 to old for the module?

ERROR: Module is not installable because not all required dependencies are currently met.

I run PW 3.0.3.2 - error says that version is to old for the module:

"Requires ProcessWire 3.0.32 < 3.0" <-- ????

In case this is a PW bug I reported that also for PW already.

Error when using a large (>2MB) pdf file

Hi @uiii if I try to upload the attached pdf mylarge.pdf, I get an error "Unable to create new image". The file itself seems to upload fine, but then when the image is generated (in backend), the error occurs.

Is there any way to prevent this? Maybe this has to do with memory limits?
Maybe we could use the resize option of imagemagick when the image is beeing created? How would one do that?
mylarge.pdf

Class 'FieldtypePDF\PDFConverter' not found

I got this error when I was adding a new (the first) field with FieldtypePDF. I have just installed a new ProcessWire site, and this is one of the very few modules I have installed (LoginPersist, Language support, 2 factor auth, Upgrades).

ProcessWire version: 3.0.153 dev

Error:

Fatal feil: Uncaught Error: Class 'FieldtypePDF\PDFConverter' not found in site/modules/FieldtypePDF/FieldtypePDF.module:108

#0 wire/core/Wire.php (383): FieldtypePDF->___getConfigInputfields(Object(Field))
#1 wire/core/WireHooks.php (823): Wire->_callMethod('___getConfigInp...', Array)
#2 wire/core/Wire.php (450): WireHooks->runHooks(Object(FieldtypePDF), 'getConfigInputf...', Array)
#3 wire/core/Field.php (1009): Wire->__call('getConfigInputf...', Array)
#4 wire/core/Wire.php (380): Field->___getConfigInputfields()
#5 wire/core/WireHooks.php (823): Wire->_callMethod('___getConfigInp...', Array)
#6 /home/snobjzfu/bloggarkivet.snobjorn.no (linje 108 i site/modules/FieldtypePDF/FieldtypePDF.module)

Denne feilmeldingen ble vist fordi: du er logget inn som Superuser. Feil har blitt loggført.

Doesn't fix namespaces when upgraded on PW 3.x

When the module is upgraded to new version on PW 3.x it won't fix the namespaces in files to be compatible with PW 3.x.

Transparent PNG?

Really? :p

I thought it would create a JPG. Can this be changed or made configurable?

A little transparent png thumb 150kb isn't that nice :D
Thanks.

Thumb in editor doesn't show.

Not sure what's about it, I have this installed in PW 2.5.3 and there's not thumb showing in editor. It works fine on front-end to generate the image from the pdf.

I noticed that Inputfield ___renderItem() doesn't really get called...

aded config array for quality and changed from png to jpeg

See my fork https://github.com/somatonic/ProcessWire-FieldtypePDF

I also added regex for png and jpg in case of backward compatiblity

Maybe you can implement this?

Creating a new field leaves the field unconfigured.

PW 2.5 +
I think this has to do with you hiding (removing!) the "extensions" config field. No matter what I do ,PW spits a warning.

Requirements

Update README listing all PHP requirements (ImageMagick, Ghostscript), and add code to the module to check them before installation.

I installed this module and get an Strict Standards notice

Strict Standards: Declaration of PagePDF::___changed() should be compatible with that of Pagefile::___changed() in /site/modules/FieldtypePDF/PagePDF.php on line 3

This is with PW 2.5.3

Page number

Add parameter to thumbnail function to specify the page number the thumbnail to generate of.