locomotivemtl / charcoal-image-compression
Charcoal module to handle image compression through compression api providers
Requires
- php: >=7.4
- ext-pdo: *
- locomotivemtl/charcoal-config: ^0.10.1
- locomotivemtl/charcoal-core: ^0.6.4
- locomotivemtl/charcoal-factory: ^0.4.2
- pimple/pimple: ^3.5
- tinify/tinify: ^1.5
Requires (Dev)
- locomotivemtl/charcoal-app: ^0.9.2
- php-coveralls/php-coveralls: ^2.2
- phpunit/phpunit: ^7.4
- squizlabs/php_codesniffer: ^3.6
Suggests
- locomotivemtl/charcoal-admin: Allows for managing and image compression and viewing results of compressions.
- locomotivemtl/charcoal-app: Needed to use the image compression module instead of the service provider for bootstrapping.
This package is auto-updated.
Last update: 2024-10-27 19:27:52 UTC
README
A Charcoal module to handle image compression through compression api providers
Installation
The preferred (and only supported) method is with Composer:
composer require locomotivemtl/charcoal-image-compression
Dependencies
Required
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.
Example: Minimum configuration via image_compression
definition
"image_compression": { "providers": [/* … */] }
Example: Minimum configuration via modules
definition
"modules": { "charcoal/image-compression/image-compression": { "providers": [/* … */] } }
Example: Full configuration via modules
definition with default options
"modules": { "charcoal/image-compression/image-compression": { "registryObject": "charcoal/image-compression/model/registry", "batchConfig": { "fileExtensions": [ "jpg", "jpeg", "png" ], "basePath": "uploads" }, "providers": [/* … */] } },
Module Options
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": "XXXXXX" } ] }
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
List of available providers
Usage
TODO
By default, if 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.
# Using default path from configuration vendor/bin/charcoal admin/image-compression/batch-compress # Using a custom path vendor/bin/charcoal admin/image-compression/batch-compress --path my/custom/path
Image Compressor
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 withcomposer phpcbf
.
Credits
License
Charcoal is licensed under the MIT license. See LICENSE for details.