README

A PHP library for advanced file compression. Currently focused on high-quality PDF optimization and image compression using Ghostscript.

Requirements

PHP: >= 8.2
External: Ghostscript (gs) must be installed.

Installation

composer require gomdim-apps/slimmer

Basic Usage

use GomdimApps\Slimmer\Optimizers\PdfOptimizer;

$optimizer = new PdfOptimizer();

// Returns float ratio of reduction (e.g., 0.4523 = 45.23% reduction)
$ratio = $optimizer
    ->withQuality('screen')
    ->optimize('input.pdf', 'output.pdf');

Advanced Configuration

Custom Ghostscript Binary

If Ghostscript is not in your PATH or you have a specific version:

use GomdimApps\Slimmer\Engines\GhostscriptEngine;
use GomdimApps\Slimmer\Optimizers\PdfOptimizer;

$engine = new GhostscriptEngine('/usr/local/bin/gs');
$optimizer = new PdfOptimizer($engine);

// Check Ghostscript version
echo $engine->getVersion(); // e.g. "9.54.0"

Process Timeout

Set a maximum execution time (in seconds, supports decimals) to prevent Ghostscript from hanging indefinitely:

$engine->setTimeout(0.5); // 500ms limit
$optimizer = new PdfOptimizer($engine);

PDF Quality Presets

The withQuality() method accepts the following presets:

Preset	DPI	Description
`screen`	72	Smallest size, lowest quality. Best for web.
`ebook`	150	Balanced quality and size. (Default)
`printer`	300	High quality for printing.
`prepress`	300	Maximum quality, color preserving.
`default`	-	System default (usually matches `printer`).

Image Optimization

Slimmer supports compressing images (JPG, PNG) while maintaining their original dimensions.

use GomdimApps\Slimmer\Optimizers\ImageOptimizer;

$optimizer = new ImageOptimizer();

// Set numeric quality from 0 to 100 (Default: 75)
$ratio = $optimizer
    ->withQuality(60)
    ->optimize('input.jpg', 'output.jpg');

Image Configuration

Supported Formats: Input and output can be .jpg, .jpeg, or .png.
Quality: Accepts an integer between 0 (maximum compression) and 100 (best quality).
Auto-Dimensioning: The library automatically detects the original image dimensions.

Custom Dimensions: Manually force specific dimensions:

$optimizer->withDimensions(800, 600)->optimize('in.jpg', 'out.jpg');

Streams & Buffers (In-Memory Optimization)

Slimmer can handle input directly from memory or streams, managing the temporary files required by Ghostscript automatically.

use GomdimApps\Slimmer\Optimizers\PdfOptimizer;

$optimizer = new PdfOptimizer();

// From a String
$pdfContent = file_get_contents('document/sample.pdf');
$ratio = $optimizer->fromString($pdfContent)->optimize(null, 'output.pdf');

// From a Stream
$stream = fopen('document/image.jpg', 'rb');
$ratio = $optimizer->fromStream($stream)->optimize(null, 'output.pdf');
fclose($stream);

Additional Flags

Configure PDF compatibility or pass raw Ghostscript arguments:

$optimizer
    ->withCompatibilityLevel('1.5')
    ->withExtraArgs(
        '-dColorConversionStrategy=/sRGB',
        '-dProcessColorModel=/DeviceRGB'
    )
    ->optimize('in.pdf', 'out.pdf');

Dry Run (Command Inspection)

Get the exact Ghostscript command string without executing it:

$command = $optimizer
    ->withQuality('screen')
    ->dryRun('input.pdf', 'output.pdf');

echo $command; // "gs -sDEVICE=pdfwrite ..."

Error Handling

The library throws GomdimApps\Slimmer\Exceptions\SlimmerException for all errors (file not found, engine failure, etc.).

try {
    $optimizer->optimize('in.pdf', 'out.pdf');
} catch (\GomdimApps\Slimmer\Exceptions\SlimmerException $e) {
    // Handle error (e.g., log $e->getMessage())
}

Troubleshooting

PHP Permission Failures (proc_open)

If you encounter permission denied errors or failures when PHP attempts to execute the Ghostscript (gs) binary (especially if installed locally in a bin folder or similar), check the following:

Execution Permissions: Ensure the PHP process user (e.g., www-data or php-fpm) has execute permissions on the Ghostscript binary:
```
chmod +x /path/to/bin/gs
```
open_basedir Restrictions: Check your php.ini configuration to ensure that the directory containing the Ghostscript binary is allowed by the open_basedir directive.
SELinux / AppArmor: Security modules like SELinux or AppArmor might restrict PHP from executing external binaries. You may need to configure policies to allow the PHP process to run gs.
Disabled Functions: Ensure that proc_open, proc_close, proc_get_status, and proc_terminate are not restricted in the disable_functions directive in your php.ini.

Docker Testing

Run the test suite in an isolated environment:

make test

License

MIT

gomdim-apps / slimmer

Maintainers

Package info

Statistics

Security