PHPackages                             locomotivemtl/charcoal-image-compression - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image &amp; Media](/categories/media)
4. /
5. locomotivemtl/charcoal-image-compression

ActiveLibrary[Image &amp; Media](/categories/media)

locomotivemtl/charcoal-image-compression
========================================

Charcoal module to handle image compression through compression api providers

0.2.0(2y ago)2627↓100%1[2 PRs](https://github.com/locomotivemtl/charcoal-image-compression/pulls)MITPHPPHP &gt;=7.4

Since Apr 7Pushed 2y ago3 watchersCompare

[ Source](https://github.com/locomotivemtl/charcoal-image-compression)[ Packagist](https://packagist.org/packages/locomotivemtl/charcoal-image-compression)[ Docs](https://locomotivemtl.github.io/charcoal-image-compression/)[ RSS](/packages/locomotivemtl-charcoal-image-compression/feed)WikiDiscussions master Synced today

READMEChangelog (2)Dependencies (9)Versions (6)Used By (0)

Charcoal ImageCompression
=========================

[](#charcoal-imagecompression)

[![License](https://camo.githubusercontent.com/587c3198494ff2d359f5c404786564a6a4382e06cb911de1f4ad42cd8660fc3b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6c6f636f6d6f746976656d746c2f63686172636f616c2d696d6167652d636f6d7072657373696f6e3f7374796c653d666c61742d737175617265)](https://packagist.org/packages/locomotivemtl/charcoal-image-compression)[![Latest Stable Version](https://camo.githubusercontent.com/fb2f606b96fcdde91c74267cd465d9914b6c8b8a8476eee673915073a0e61de8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c6f636f6d6f746976656d746c2f63686172636f616c2d696d6167652d636f6d7072657373696f6e3f7374796c653d666c61742d737175617265)](https://packagist.org/packages/locomotivemtl/charcoal-image-compression)[![Build Status](https://camo.githubusercontent.com/0f6e90fcd322edc6f51cfeab966e9af31017831a7c01d949117a1fce25580e7f/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6c6f636f6d6f746976656d746c2f63686172636f616c2d696d6167652d636f6d7072657373696f6e3f7374796c653d666c61742d737175617265)](https://travis-ci.org/locomotivemtl/charcoal-image-compression)

A [Charcoal](https://packagist.org/packages/locomotivemtl/charcoal-app) module to handle image compression through compression api providers

Installation
------------

[](#installation)

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

```
composer require locomotivemtl/charcoal-image-compression
```

### Dependencies

[](#dependencies)

#### Required

[](#required)

- [**PHP 7.4+**](https://php.net)
- [**tinify/tinify-php**](https://github.com/tinify/tinify-php)

#### PSR

[](#psr)

- [**PSR-3**](https://www.php-fig.org/psr/psr-3/): Common interface for logging libraries. Fulfilled by Monolog.
- [**PSR-11**](https://www.php-fig.org/psr/psr-11/): Common interface for dependency containers. Fulfilled by Pimple.

Service Provider
----------------

[](#service-provider)

The following services are provided with the use of [*charcoal-image-compression*](https://github.com/locomotivemtl/charcoal-image-compression)

### Services

[](#services)

- [`image-compression`](src/Charcoal/ImageCompression/Service/ImageCompressionService.php) instance of `\Charcoal\ImageCompression\Service\ImageCompression`
- [`image-compressor`](src/Charcoal/ImageCompression/ImageCompressor.php) instance of `\Charcoal\ImageCompression\ImageCompressor`

Configuration
-------------

[](#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

[](#example-minimum-configuration-via-image_compression-definition)

```
"image_compression": {
    "providers": [/* … */]
}
```

###### Example: Minimum configuration via `modules` definition

[](#example-minimum-configuration-via-modules-definition)

```
"modules": {
    "charcoal/image-compression/image-compression": {
        "providers": [/* … */]
    }
}
```

###### Example: Full configuration via `modules` definition with default options

[](#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

[](#module-options)

OptionTypeDescriptionDefault`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``string[]`List of extensions used with \[`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.`[]`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": "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-special-providers)

ProviderPackageFeatures[Chain](src/Charcoal/ImageCompression/Provider/Chain)`locomotivemtl/charcoal-image-compression/chain-provider`Chaining providers### List of available providers

[](#list-of-available-providers)

ProviderPackageFeatures[Tinify](src/Charcoal/ImageCompression/Provider/Tinify)`locomotivemtl/charcoal-image-compression/tinify-provider`JPG, PNG, [Learn more](https://tinypng.com/developers)Usage
-----

[](#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

[](#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

[](#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
-----------

[](#development)

To install the development environment:

```
composer install
```

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

```
composer test
```

### API Documentation

[](#api-documentation)

- The auto-generated `phpDocumentor` API documentation is available at:

- The auto-generated `apigen` API documentation is available at:
    [https://codedoc.pub/locomotivemtl/charcoal-image-compression/master/](https://codedoc.pub/locomotivemtl/charcoal-image-compression/master/index.html)

### Development Dependencies

[](#development-dependencies)

- \[php-coveralls/php-coveralls\]\[phpcov\]
- \[phpunit/phpunit\]\[phpunit\]
- \[squizlabs/php\_codesniffer\]\[phpcs\]

### Coding Style

[](#coding-style)

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

- [*PSR-1*](https://www.php-fig.org/psr/psr-1/)
- [*PSR-2*](https://www.php-fig.org/psr/psr-2/)
- [*PSR-4*](https://www.php-fig.org/psr/psr-4/), autoloading is therefore provided by *Composer*.
- [*phpDocumentor*](http://phpdoc.org/) comments.
- [phpcs.xml.dist](phpcs.xml.dist) and [.editorconfig](.editorconfig) for coding standards.

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

Credits
-------

[](#credits)

- [Locomotive](https://locomotive.ca/)

License
-------

[](#license)

Charcoal is licensed under the MIT license. See [LICENSE](LICENSE) for details.

###  Health Score

25

—

LowBetter than 40% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity18

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 82.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~299 days

Total

3

Last Release

846d ago

PHP version history (2 changes)0.1.0PHP &gt;7.4

0.2.0PHP &gt;=7.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/f3f29e38395113e2400bdd7e51bea982b17f120d4d5a53d4473b53118ee46f8d?d=identicon)[JoelAlphonso](/maintainers/JoelAlphonso)

---

Top Contributors

[![JoelAlphonso](https://avatars.githubusercontent.com/u/10762266?v=4)](https://github.com/JoelAlphonso "JoelAlphonso (37 commits)")[![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (8 commits)")

---

Tags

imagecompressioncompressoptimizationcharcoal

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/locomotivemtl-charcoal-image-compression/health.svg)

```
[![Health](https://phpackages.com/badges/locomotivemtl-charcoal-image-compression/health.svg)](https://phpackages.com/packages/locomotivemtl-charcoal-image-compression)
```

###  Alternatives

[ps/image-optimizer

Image optimization / compression library. This library is able to optimize png, jpg and gif files in very easy and handy way. It uses optipng, pngquant, pngcrush, pngout, gifsicle, jpegoptim and jpegtran tools.

9121.7M25](/packages/ps-image-optimizer)[joshembling/image-optimizer

Optimize your Filament images before they reach your database.

111138.7k12](/packages/joshembling-image-optimizer)[gtuk/image-optimizer

PHP image optimizer for png, jpeg and gif files. It uses mozjpeg, pngquant and gifsicle for the optimization process

161.6k](/packages/gtuk-image-optimizer)[schmitzal/tinyimg

Image compression for all pngs and jpgs uploaded to the backend (using the tinypng API)

16123.7k](/packages/schmitzal-tinyimg)[kinglozzer/tinypng

TinyPNG PHP API

1391.1k1](/packages/kinglozzer-tinypng)[sitegeist/image-jack

Jack of all trades concerning image optimization. Also introduces the usage of next-gen-image-formats

1066.7k](/packages/sitegeist-image-jack)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
