README

SSIM-based image quality verification with auto-retry compression loop for PHP 8.4+

This package does ONE job: guard image quality. It does not compress, resize, or upload images. It verifies that a compression result meets your quality threshold — and retries if not.

Requirements

• PHP 8.4+
• ext-gd (required)
• ext-imagick (optional — enables higher-precision SSIM via float pixel data)

Installation

composer require rcsofttech/php-image-guard

Quick Start

Minimal — check one image

use RcSoftTech\ImageGuard\ImageGuard;

$gdImage = imagecreatefromjpeg('original.jpg');

$result = ImageGuard::check(
    'original.jpg',
    function (int $quality, string $originalPath) use ($gdImage): string {
        $out = "/tmp/compressed_q{$quality}.jpg";
        imagejpeg($gdImage, $out, $quality);
        return $out;
    }
);

echo $result->summary();
// "Passed (SSIM: 0.961, Quality: 75, Saved: 68%, 143ms)"

Standalone SSIM score (no retry)

$score = ImageGuard::compare('original.jpg', 'compressed.jpg');
// float e.g. 0.961423

Full Fluent API

use RcSoftTech\ImageGuard\Enums\OnFailBehavior;
use RcSoftTech\ImageGuard\ImageGuard;

$result = ImageGuard::original('original.jpg')
    ->compressWith($compressor)
    ->threshold(0.92)            // or: 'strict' | 'balanced' | 'loose'
    ->startAt(75)                // initial quality integer
    ->maxQuality(95)             // ceiling for retry loop
    ->step(5)                    // quality bump per retry
    ->onFail(OnFailBehavior::RECOMPRESS)
    ->run(ImageGuard::resolveCalculator());

if ($result->failed()) {
    logger()->warning('Image below threshold', $result->toArray());
}

Quality Presets

Custom numeric thresholds are typically used in the 0.0 to 1.0 range.

Failure Behaviors

Batch API

$report = ImageGuard::batch(glob('uploads/*.jpg'))
    ->compressWith($compressor)
    ->threshold('balanced')
    ->onFail(OnFailBehavior::WARN)
    ->run(ImageGuard::resolveCalculator());

echo $report->totalSaved();  // "38.1 MB saved across 147 images"
echo $report->failRate();    // "3 of 147 failed (2.0%)"
echo $report->averageSsim(); // 0.941200

file_put_contents('audit.json', $report->toJson());
file_put_contents('audit.csv', $report->toCsv());

Compressor Examples

The compressor callable receives a quality integer and the originalPath string, and must return the path to the compressed file. This decouples php-image-guard from any specific tool.

Plain GD

$compressor = function (int $quality, string $originalPath) use ($tmpDir): string
{
    $gdImage = imagecreatefromjpeg($originalPath);
    $output = "{$tmpDir}/compressed_q{$quality}.jpg";
    imagejpeg($gdImage, $output, $quality);
    imagedestroy($gdImage);
    return $output;
};

With spatie/image-optimizer

use Spatie\ImageOptimizer\OptimizerChain;
use Spatie\ImageOptimizer\Optimizers\Jpegoptim;

$compressor = function (int $quality, string $originalPath) use ($tmpDir): string
{
    $output = "{$tmpDir}/compressed_q{$quality}.jpg";
    copy($originalPath, $output);
    (new OptimizerChain)->addOptimizer(
        new Jpegoptim(['--max=' . $quality])
    )->optimize($output);
    return $output;
};

With intervention/image

$compressor = function (
    int $quality,
    string $originalPath,
) use ($manager, $tmpDir): string {
    $output = "{$tmpDir}/compressed_q{$quality}.webp";
    $manager->read($originalPath)->toWebp($quality)->save($output);
    return $output;
};

PipelineResult Shape

$result->passed          // bool
$result->ssimScore       // float e.g. 0.961423
$result->threshold       // float e.g. 0.92
$result->qualityUsed     // int — final quality used
$result->attempts        // int — number of retry attempts
$result->originalSize    // int — bytes
$result->compressedSize  // int — bytes
$result->savingsPercent  // float e.g. 68.4
$result->formatInput     // string e.g. 'jpeg'
$result->formatOutput    // string e.g. 'webp'
$result->durationMs      // int — total pipeline time
$result->outputPath      // string — path to accepted output
$result->warnings        // string[] — any warnings

$result->summary()       // "Passed (SSIM: 0.961, Quality: 75, Saved: 68%, 143ms)"
$result->savings()       // "68%"
$result->passed()        // bool
$result->failed()        // bool
$result->toArray()       // array<string, mixed>
$result->toJson()        // JSON string

SSIM Accuracy

These are practical expectations aligned with the current test suite and generated fixtures (not universal guarantees for every image set).

License

MIT — see LICENSE.