Charcoal ImageCompression

A Charcoal module to handle image compression through compression api providers

Table of Contents

• Installation
  • Dependencies
• Service Provider
  • Services
• Configuration
• Usage
• Development
  • API Documentation
  • Development Dependencies
  • Coding Style
• Credits
• License

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-image-compression

Dependencies

Required

• PHP 7.4+
• tinify/tinify-php

PSR

• PSR-3: Common interface for logging libraries. Fulfilled by Monolog.
• PSR-11: Common interface for dependency containers. Fulfilled by Pimple.

Service Provider

The following services are provided with the use of charcoal-image-compression

Services

• image-compression instance of \Charcoal\ImageCompression\Service\ImageCompression
• image-compressor instance of \Charcoal\ImageCompression\ImageCompressor

Configuration

The configuration of the comporession module is done via the modules key of the project configuration. Charcoal image is hooked to use the compression module automatically once configured.

{
    // Full config with defaults options
    "modules": {
        "charcoal/image-compression/image-compression": {
            "autoCompress": true,
            "registryObject": "charcoal/image-compression/model/registry",
            "batchConfig": {
                "fileExtensions": [ "jpg", "jpeg", "png" ],
                "basePath": "uploads"
            },
            "providers": [...]
        }
    },
    
    // Minimum config
    "modules": {
        "charcoal/image-compression/image-compression": {
            "providers": [...]
        }
    }
}

Module Options

Option	Type	Description	Default
autoCompress	bool	(todo) Whether to compress files when they are saved in charcoal	true
registryObject	string	The registry object to keep track of compression	charcoal/image-compression/model/registry
batchConfig	object	Options for the batch compression process	n/a
___fileExtension	array	List of extensions to glob	[ "jpg", "jpeg", "png" ]
___basePath	string	The base path to glob from	uploads
providers	array	List of providers with their options. Each provider have it’s own set of options to define. To learn more, refere to the following section about providers.	[]

Providers

The providers key can be used to list and configured some providers that are tasked to bridge the gaps between Charcoal and the different apis. Each providers defines their own options. Here’s an example of a provider configuration for tinify provider.

{
    "providers": [
        {
            "type": "tinify",
            "key": "sdkfjeiSADkd",
            "maxCompressions": 500
        }
    ]
}

Multiple providers can be used at the same time and will be chained one after the other so that if a provider as reached a limit or fails, the next one on the list will be used instead.

List of special providers

Provider	Package	Feature	Stats
Chain	locomotivemtl/charcoal-image-compression/chain-provider	Chaining providers

List of available providers

Provider	Package	Feature	Stats
Tinify	locomotivemtl/charcoal-image-compression/tinify-provider	Jpg, png Website

Usage

By default, if a configuration for a provider is defined in the module’s configuration, Charcoal Image properties will compress the uploaded images on the image save callback. Must use the option autoCompress set to true which is the default behavior.

Script

A script is provided to compress images on the server in a batch.

# default path
$ vendor/bin/charcoal admin/image-compression/batch-compress

# with custom path
$ vendor/bin/charcoal admin/image-compression/batch-compress --path my/custom/path

ImageCompressor

The compression module can also be used as a standalone module via the ImageCompressor class. A container service is provided to access it.

// Fetch image conmpression from pimple container
$this->imageCompressor = $container['image-compressor'];

// The compress method is used to compress a source file path to a target path.
$this->imageCompressor->compress($source, $target)

The ImageCompressor class will use the predefined module configuration and providers. For a custom implementation, instantiate the providers manually

use Charcoal\ImageCompression\Provider\Tinify\TinifyProvider;

$provider = new TinifyProvider([...]);
$provider->compress($source, $target);

// Or use the special Chain Provider to chain providers together

use Charcoal\ImageCompression\Provider\Tinify\TinifyProvider;
use Charcoal\ImageCompression\Provider\Chain\ChainProvider;

$chainProvider = new ChainProvider([
    new TinifyProvider([...])
]);

$chainProvider->compress($source, $target);

Development

To install the development environment:

$ composer install

To run the scripts (phplint, phpcs, and phpunit):

$ composer test

API Documentation

• The auto-generated phpDocumentor API documentation is available at:
  https://locomotivemtl.github.io/charcoal-image-compression/docs/master/
• The auto-generated apigen API documentation is available at:
  https://codedoc.pub/locomotivemtl/charcoal-image-compression/master/

Development Dependencies

• [php-coveralls/php-coveralls][phpcov]
• [phpunit/phpunit][phpunit]
• [squizlabs/php_codesniffer][phpcs]

Coding Style

The charcoal-image-compression module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• phpcs.xml.dist and .editorconfig for coding standards.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Credits

• Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.