PHPackages                             piplup/imagex - 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 & Media](/categories/media)
4. /
5. piplup/imagex

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

piplup/imagex
=============

Headless PHP image optimization library

00PHP

Since Apr 20Pushed 3mo agoCompare

[ Source](https://github.com/sadik-malik/piplup-imagex-php)[ Packagist](https://packagist.org/packages/piplup/imagex)[ RSS](/packages/piplup-imagex/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependenciesVersions (1)Used By (0)

Piplup ImageX
=============

[](#piplup-imagex)

Headless PHP image optimization library — generate responsive variants, convert formats, and manage storage/CDN integration.

Table of contents
-----------------

[](#table-of-contents)

- [Overview](#overview)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start](#quick-start)
- [API Reference](#api-reference)
    - [Image attributes](#image-attributes)
    - [Variant generation](#variant-generation)
    - [Storage adapters](#storage-adapters)
    - [Converters & Resizers](#converters--resizers)
    - [Compression helpers](#compression-helpers)
    - [CLI](#cli)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

Overview
--------

[](#overview)

`Piplup/ImageX` is a small, framework-agnostic PHP library that helps you:

- Inspect images and produce `srcset`-ready attributes.
- Generate responsive variants, store them (local or S3), and produce CDN-ready URLs.
- Convert and compress images using either binary tools, Imagick or simple copy fallbacks.
- Provide a tiny CLI for simple automation.

The library is intentionally small and explicit — it provides building blocks that you can compose in your application.

Features
--------

[](#features)

- Compute `src`, `srcset`, `sizes`, `width`, `height`, and MIME `type` for images.
- Generate responsive variants and store them with pluggable storage adapters.
- Multiple converter implementations: Imagick, binary-command based, and a null (copy) converter.
- Resizer that uses Imagick when available and falls back to GD.
- Smart compression recommendations driven by configurable compression profiles.
- Built-in CLI: `generate`, `convert`, `regenerate`.

Requirements
------------

[](#requirements)

- PHP 8.0 or later (see `composer.json`).
- Optional but recommended: `ext-imagick` for best quality image ops.
- Optional CLI tools for some conversions: `cwebp`, `avifenc` (used by `BinaryConverter`).

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

[](#installation)

Install via Composer:

```
composer require piplup/imagex
```

This package follows PSR-4 autoloading under the `Piplup\ImageX\` namespace.

Quick start
-----------

[](#quick-start)

1. Simple attributes extraction (generates `srcset` automatically):

```
use Piplup\ImageX\ImageManager;

$mgr = new ImageManager();
$attrs = $mgr->getAttributes('/path/to/image.jpg', [
	'widths' => [320, 640, 1024],
	'sizes' => '(max-width: 600px) 100vw, 50vw',
]);

// $attrs contains: src, srcset, sizes, width, height, type
print_r($attrs);
```

2. Generate responsive variants and store them (local storage + binary converter example):

```
use Piplup\ImageX\Resizer\SimpleResizer;
use Piplup\ImageX\Adapters\LocalStorageAdapter;
use Piplup\ImageX\Converters\BinaryConverter;
use Piplup\ImageX\Manager\VariantManager;

$resizer = new SimpleResizer();
$storage = new LocalStorageAdapter(__DIR__ . '/public/uploads', 'https://example.com/uploads');
$converter = new BinaryConverter();

$vm = new VariantManager($resizer, $storage, $converter);
$variants = $vm->generateVariants('/path/to/image.jpg', [
	'format' => 'webp',
	'storage_path' => 'images/variants',
	'widths' => [320, 640, 1280],
]);

print_r($variants);
// Each variant: ['url' => ..., 'width' => 320, 'path' => 'images/variants/2026/04/name-320w.webp', 'created' => true]
```

API Reference
-------------

[](#api-reference)

Below are the main classes and how to use them. For more details see the source files in `src/`.

### Image attributes

[](#image-attributes)

- `Piplup\ImageX\ImageManager` — convenience wrapper to get image attributes. See [src/ImageManager.php](src/ImageManager.php).
- `Piplup\ImageX\ImageAttributesFactory` — main logic for `getAttributes(string $path, array $options = [])`. Returns an array with keys: `src`, `srcset`, `sizes`, `width`, `height`, `type`. See [src/ImageAttributesFactory.php](src/ImageAttributesFactory.php).

Options supported by `getAttributes` include:

- `widths`: array of integers (explicit widths to include in `srcset`).
- `sizes`: string for the `sizes` attribute (defaults to `100vw`).
- `generated_variants`: an array of pre-generated variant records (will be used instead of computing local widths).
- `storage_adapter`: instance implementing `Piplup\ImageX\Contracts\StorageAdapterInterface` (used to map stored paths to URLs).

### Variant generation

[](#variant-generation)

- `Piplup\ImageX\Manager\VariantManager` — generate or ensure responsive variants exist and are stored via a `StorageAdapterInterface`. See [src/Manager/VariantManager.php](src/Manager/VariantManager.php).

Key options for `ensureVariants` / `generateVariants`:

- `storage_path`: base path used in storage for generated variants (default `uploads/variants`).
- `format`: desired output extension/format (e.g. `webp`).
- `widths`, `breakpoints`, `dprs`: forwarded to the generator.
- `resize_options`: options passed to the resizer (e.g. `['quality'=>80, 'format'=>'webp']`).

Return value: array of variant metadata: `['url' => string, 'width' => int, 'path' => string, 'created' => bool]`.

### Storage adapters

[](#storage-adapters)

- `Piplup\ImageX\Adapters\LocalStorageAdapter` — store files on local disk and optionally map to a `baseUrl`. See [src/Adapters/LocalStorageAdapter.php](src/Adapters/LocalStorageAdapter.php).
- `Piplup\ImageX\Adapters\S3StorageAdapter` — store via an S3-compatible client (expects an SDK client). See [src/Adapters/S3StorageAdapter.php](src/Adapters/S3StorageAdapter.php).

Both adapters implement `Piplup\ImageX\Contracts\StorageAdapterInterface` with methods: `put`, `exists`, `url`, `get`, `delete`.

### Converters & Resizers

[](#converters--resizers)

- `Piplup\ImageX\Converters\ImagickConverter` — uses `ext-imagick` to convert images (falls back to copy when unavailable). See [src/Converters/ImagickConverter.php](src/Converters/ImagickConverter.php).
- `Piplup\ImageX\Converters\BinaryConverter` — attempts to use command-line tools (`cwebp`, `avifenc`) then Imagick then copy. See [src/Converters/BinaryConverter.php](src/Converters/BinaryConverter.php).
- `Piplup\ImageX\Converters\NullConverter` — simple copy converter.
- `Piplup\ImageX\Resizer\SimpleResizer` — resizes images using Imagick when available, otherwise uses GD. See [src/Resizer/SimpleResizer.php](src/Resizer/SimpleResizer.php).

The converter interface is `Piplup\ImageX\Contracts\ConverterInterface::convert(string $sourcePath, string $targetPath, array $options = [])`.

### Compression helpers

[](#compression-helpers)

- `Piplup\ImageX\Compression\CompressionProfile` — configure which formats to recommend and their thresholds. See [src/Compression/CompressionProfile.php](src/Compression/CompressionProfile.php).
- `Piplup\ImageX\Compression\SmartCompression` — inspect metadata (mime, size) and return recommendations: `['conversions'=>[['format'=>'webp','quality'=>80],...],'keep_original'=>bool,'remove_if_larger'=>bool]`. See [src/Compression/SmartCompression.php](src/Compression/SmartCompression.php).

Example:

```
use Piplup\ImageX\Compression\CompressionProfile;
use Piplup\ImageX\Compression\SmartCompression;
use Piplup\ImageX\Config\Config;

$profile = CompressionProfile::fromArray([
	'webp' => ['quality' => 80, 'min_size' => 10240],
	'avif' => ['quality' => 50, 'min_size' => 32768],
]);

$smart = new SmartCompression($profile, Config::fromArray(['quality' => 75]));
$rec = $smart->recommend(['mime' => 'image/jpeg', 'size' => filesize('/path/to/image.jpg')]);
print_r($rec);
```

### CLI

[](#cli)

There is a tiny CLI entrypoint at `bin/compressx` that exposes three commands:

- `generate`: basic front for `ImageManager` (can use `IMAGE_MANAGER_CLASS` env to point to custom implementation).
- `convert`: run conversion helper commands.
- `regenerate`: placeholder to trigger regeneration flows.

Example:

```
php bin/compressx generate /path/to/image.jpg --widths=320,640 --sizes='100vw'

# Use a custom manager implementation via env:
IMAGE_MANAGER_CLASS=\MyApp\CustomImageManager php bin/compressx generate /path/to/image.jpg
```

The CLI commands are intentionally minimal and return JSON to make automation simple.

Testing
-------

[](#testing)

Unit tests are available under `tests/`. Run the test suite with Composer:

```
composer install --dev
composer test
```

Or directly:

```
vendor/bin/phpunit
```

Contributing
------------

[](#contributing)

- Fork and send a PR.
- Keep changes small and focused.
- Run tests before submitting.

Troubleshooting & notes
---------------------------

[](#troubleshooting--notes)

- If `ext-imagick` is not installed, the library falls back to GD or simple copy behavior — some features and quality optimizations will be limited.
- `BinaryConverter` will attempt to use `cwebp` and `avifenc` if present on the system `PATH`.
- `S3StorageAdapter` expects a working S3-like client (AWS SDK or compatible). It uses method names such as `putObject`, `getObject` or `headObject` depending on the client implementation.

License
-------

[](#license)

This project is licensed under the MIT License. See `composer.json` for package metadata.

###  Health Score

18

—

LowBetter than 7% of packages

Maintenance55

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/4924096?v=4)[piplup](/maintainers/piplup)[@piplup](https://github.com/piplup)

---

Top Contributors

[![sadik-malik](https://avatars.githubusercontent.com/u/38027249?v=4)](https://github.com/sadik-malik "sadik-malik (1 commits)")

### Embed Badge

![Health badge](/badges/piplup-imagex/health.svg)

```
[![Health](https://phpackages.com/badges/piplup-imagex/health.svg)](https://phpackages.com/packages/piplup-imagex)
```

###  Alternatives

[char0n/ffmpeg-php

PHP wrapper for FFmpeg application

495240.6k1](/packages/char0n-ffmpeg-php)[goat1000/svggraph

Generates SVG graphs

135911.1k3](/packages/goat1000-svggraph)[gravatarphp/gravatar

Gravatar URL builder which is most commonly called as a Gravatar library

12653.6k2](/packages/gravatarphp-gravatar)

PHPackages © 2026

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