mirko-pagliai/cakephp-thumber

Thumber plugin for CakePHP

1.12.0 2024-01-05 11:03 UTC

Requires

• php: >=8.1
• ext-fileinfo: *
• cakephp/cakephp: ^5.0
• intervention/image: ^2.4
• mirko-pagliai/php-thumber: ~1.6.1
• mirko-pagliai/php-tools: ~1.9.3

Requires (Dev)

• cakephp/cakephp-codesniffer: ^5.0
• phpstan/phpstan: ^1.10.38
• phpunit/phpunit: ^10.1.0 <=10.5.3
• vimeo/psalm: ^5.15.0

MIT

• Mirko Pagliai

README

cakephp-thumber is a CakePHP plugin to create thumbnails.

It uses intervention/image and provides:

• ThumbCreator, an utility to create thumbnails;
• ThumbHelper, a convenient helper that allows you to create thumbnails on the fly from your templates.

Starting from 1.8.0 release, much of the code has been moved into the php-thumber package, so that it becomes a php library independent from CakePHP. This plugin continues to exist and all classes and methods remain unchanged, but it only includes the code closely related to CakePHP (commands, helpers, middlewares, etc). The namespace prefix is now Thumber\Cake and no longer Thumber.

Did you like this plugin? Its development requires a lot of time for me. Please consider the possibility of making a donation: even a coffee is enough! Thank you.

• Requirements and supported formats
• Installation
  • Installation on older CakePHP and PHP versions
    • For PHP 8.0 and CakePHP 4 or later
    • For PHP 7.2 or later
    • For PHP 5.6 and CakePHP 3 or later
• Configuration
  • Configuration values
• How to use
• Testing
• Versioning

Requirements and supported formats

cakephp-thumber requires GD Library (>=2.0) or Imagick PHP extension (>=6.5.7). It's highly preferable to use Imagick, because It provides better performance and a greater number of supported formats.

Supported formats may vary depending on the library used.

For more information about supported format, please refer to the Intervention Image documentation.

Installation

You can install the plugin via composer:

$ composer require --prefer-dist mirko-pagliai/cakephp-thumber

Then you have to load the plugin. For more information on how to load the plugin, please refer to the Cookbook.

Simply, you can execute the shell command to enable the plugin:

bin/cake plugin load Thumber/Cake

This would update your application's bootstrap method.

By default the plugin uses the APP/tmp/thumbs directory to save the thumbnails. So you have to create the directory and make it writable:

$ mkdir tmp/thumbs && chmod 775 tmp/thumbs

If you want to use a different directory, read the Configuration section.

Installation on older CakePHP and PHP versions

Recent packages and the master branch require at least CakePHP 5.0 and PHP 8.1 and the current development of the code is based on these and later versions of CakePHP and PHP. However, there are still some branches compatible with previous versions of CakePHP and PHP.

For PHP 8.0 and CakePHP 4 or later

The cakephp4 branch requires at least PHP >=7.4 and CakePHP ^4.4.

In this case, you can install the package as well:

$ composer require --prefer-dist mirko-pagliai/cakephp-thumber:dev-cakephp4

Note that the cakephp4 branch will no longer be updated as of January 5, 2024, except for security patches, and it matches the 1.11.3 version.

For PHP 7.2 or later

The php7.2 branch requires at least PHP 7.2.

In this case, you can install the package as well:

$ composer require --prefer-dist mirko-pagliai/cakephp-thumber:dev-php7.2

Note that the php7.2 branch will no longer be updated as of April 29, 2022, except for security patches, and it matches the 1.9.9 version.

For PHP 5.6 and CakePHP 3 or later

The cakephp3 branch requires at least PHP 5.6 and CakePHP 3.

In this case, you can install the package as well:

$ composer require --prefer-dist mirko-pagliai/cakephp-thumber:dev-cakephp3

Note that the cakephp3 branch will no longer be updated as of May 7, 2021, except for security patches, and it matches the 1.9.4 version.

Configuration

The plugin uses some configuration parameters and you can set them using the \Cake\Core\Configure class, before loading the plugin.

For example, you can do this at the bottom of the file APP/config/app.php of your application.

Configuration values

Configure::write('Thumber.driver', 'imagick');

Setting Thumber.driver, you can choose which driver to use for the creation of thumbnails. Valid values are imagick or gd.

Configure::write('Thumber.target', TMP . 'thumbs');

Setting Thumber.target, you can use another directory where the plugin will save thumbnails.

How to use

See our wiki:

• How to use the helper
• How to use the ThumbCreator utility

And refer to our API.

Testing

The library (GD or Imagick) to be tested is set by the tests/bootstrap.php file, using the THUMBER_DRIVER environment variable. By default, Imagick is used.

For example:

if (!getenv('THUMBER_DRIVER')) {
    putenv('THUMBER_DRIVER=imagick');
}

Configure::write('Thumber.driver', getenv('THUMBER_DRIVER'));

Moreover, some tests belong to the imageEquals group. These tests generate thubnails and compare them with pre-loaded thumbnails (inside tests/comparing_files/). By default, these tests are not performed, because the images may be different if generated from different environments and systems.

To exclude these tests, you should run:

vendor/bin/phpunit --exclude-group imageEquals

Versioning

For transparency and insight into our release cycle and to maintain backward compatibility, Thumber will be maintained under the Semantic Versioning guidelines.