spatie/image for expressive PHP image manipulation

The image operations spatie/image exposes

spatie/image addresses a recurring application task: changing an image after it has been uploaded, generated, or stored elsewhere. It is aimed at PHP developers who want image manipulation in application code rather than a separate image editor or command-line pipeline. The package supports operations such as fitting an image into a rectangle, converting it to greyscale, changing brightness and quality, rotating it, and sharpening it.

The main design choice is an expressive, chainable API. Instead of requiring callers to coordinate separate function calls for each stage, the package presents each operation as a method on an image object. That makes the order of transformations visible in the source and keeps common image pipelines compact.

The package is not a complete media library. The repository describes spatie/image as an image manipulation component, while the README does not document storage, uploads, responsive variants, database records, or deletion policies. Those concerns belong to the surrounding application or another package. A team that needs only pixel transformations can use this package directly, while a team expecting media asset management should not treat it as a substitute for a full media library.

The repository also states that large parts of the codebase were copied from Intervention Image and modified for readability and for the package's needs. That history explains the familiar image-processing vocabulary, but the API documented here is specifically spatie/image's public surface.

The fluent transformation pipeline in spatie/image

The documented flow begins with `Image::load($pathToImage)`, which loads an image from a path. The returned object then receives one or more operations, followed by `save()`. In the README's sizing example, `width(100)` and `height(100)` express a target rectangle of 100 by 100, while the accompanying comment states that the aspect ratio is preserved.

Other operations modify visual characteristics directly. `greyscale()` converts the image to greyscale, `brightness(-30)` reduces brightness, and `quality(25)` requests low output quality. `orientation(90)` rotates the image, and `sharpen(15)` applies a sharpening operation. These methods can be chained before saving, which means a single pipeline can combine geometric and appearance changes.

The API is intentionally centered on an image instance rather than a large procedural configuration object. The examples show that the path is supplied at the beginning, while the destination can be supplied to `save($pathToNewImage)` or omitted when the original file should be overwritten. The README also documents saving a transformed image over the original in its greyscale example. That behavior requires care in an application, because an accidental call to `save()` can replace the source image.

The README names GD, ImageMagick, PHP, and related image topics, but the repository excerpt does not specify which extension must be selected for a particular operation. It also does not document format support, memory limits, color-profile handling, animated images, or error behavior in detail. Those are important boundaries when deciding whether the package fits an application with specialized image requirements.

Installing spatie/image and running a first transformation

The README gives one Composer installation command. It also states that version 1.5.3 and later require the PHP `exif` extension to be enabled. The extension note links to PHP's exif installation documentation, so an adopter must confirm that the extension is available to the PHP process before relying on the package.

Run this from the PHP project that should depend on spatie/image:

composer require spatie/image

After Composer completes, the package can be imported through its PHP namespace. The following example loads an existing image, fits it within a 100 by 100 rectangle without changing its aspect ratio, and saves it under a new path:

use Spatie\Image\Image;

Image::load($pathToImage)
   ->width(100)
   ->height(100)
   ->save($pathToNewImage);

The variables are application values, not additional package configuration. The path passed to `Image::load()` must identify an existing image, and `$pathToNewImage` identifies the output file. The README does not specify whether the destination directory must already exist or how an invalid path is reported, so the application should handle path validation and filesystem errors separately.

A second first use can change appearance while preserving the original through an explicit destination:

use Spatie\Image\Image;

Image::load($pathToImage)
   ->greyscale()
   ->save($pathToNewImage);

The README's original example omits the destination for an overwrite, but the explicit output path makes the example safer to understand. It also shows that saving is part of the transformation pipeline rather than an implicit side effect of the final operation.

Brightness, quality, rotation, and sharpening constraints

spatie/image supports several operations that are useful for generated assets or application-specific derivatives. The README demonstrates brightness adjustment together with output quality:

use Spatie\Image\Image;

Image::load($pathToImage)
   ->brightness(-30)
   ->quality(25)
   ->save();

The `brightness(-30)` call represents a darker result, and `quality(25)` requests a low-quality output according to the README comment. The package does not document the accepted range for either setting in the excerpt. An application should therefore avoid assuming that values outside the examples are valid or that quality changes affect a particular file format in the same way.

Rotation and sharpening are likewise available through a chain:

use Spatie\Image\Image;

Image::load($pathToImage)
   ->orientation(90)
   ->sharpen(15)
   ->save();

Here, `orientation(90)` rotates the image and `sharpen(15)` sharpens it, as described in the README. The documentation does not state how multiple calls interact with dimensions, image orientation metadata, or sharpening quality on different inputs. That makes this API convenient for straightforward transformations, but not sufficiently documented for a workflow that depends on exact pixel output.

The repository includes `composer.json`, `phpstan.neon.dist`, `phpstan-baseline.neon`, `phpunit.xml.dist`, and `tests/`, indicating a PHP package with configured static analysis and test infrastructure. The excerpt does not describe the supported PHP versions, so those versions should be checked in `composer.json` and the project documentation before installation.

Testing spatie/image and understanding maintenance cost

The README gives a test command sequence that installs the JavaScript comparison dependency and runs the PHP test suite:

npm i pixelmatch
composer test

`package.json` lists `pixelmatch` and `pngjs` as dependencies, which is consistent with image comparison fixtures involving PNG output. The README does not explain the fixture format or the visual tolerance used by the tests, so the test command should be treated as the project's documented entry point rather than as a guarantee that every transformation matches a particular external implementation.

Maintenance activity is visible in the repository metadata. The project is not archived, the last push was on 2026-10-05, and recent releases include 3.9.7 on 2026-09-30, 3.9.6 on 2026-08-18, and 3.9.5 on 2026-06-19. This supports treating the package as recently changed, but it does not remove the need to inspect `CHANGELOG.md` for behavioral changes between versions. The project is MIT licensed, and the README points to `LICENSE.md` for the license text.

The main upgrade cost is therefore version review rather than a separately documented migration framework. The repository includes `CHANGELOG.md`, but the README excerpt does not state upgrade instructions, deprecation policy, or compatibility guarantees. A team using this package in an application should compare its current transformation calls and PHP environment with the relevant changelog entries before changing versions.

spatie/image compared with Intervention Image

Intervention Image is a real alternative because the README credits it as the source from which large parts of this codebase were copied and modified. The documented spatie/image interface uses a chain beginning with `Image::load($pathToImage)` and ending with `save()` or `save($pathToNewImage)`, with operations such as `width()`, `height()`, `greyscale()`, `brightness()`, `quality()`, `orientation()`, and `sharpen()` in between.

The practical difference is not a claimed performance difference, since neither the README nor the repository files provide benchmarks. The difference is the package identity and API surface. A project already standardized on Intervention Image may prefer to retain its existing API and dependency conventions. A project choosing a PHP package now can adopt spatie/image's documented chain without switching terminology in its application code. The repository does not provide a feature-by-feature comparison, so the choice should not be based on assumptions about format support, performance, or plugin availability.

Intervention Image is also the relevant comparison for licensing and provenance. The README identifies Intervention Image as the origin of copied code and states that spatie/image is MIT licensed. It does not provide further licensing analysis, so users should read `LICENSE.md` and inspect any dependency notices when distribution requirements matter.

Editorial conclusion

Developers should adopt spatie/image when their PHP application needs concise image transformations through a fluent API and can operate in an environment with the required exif extension. It is a poorer fit for a command-line image workflow, unsupported format requirements, or projects that need controls not documented here. Before adoption, verify that the target images, required PHP extensions, output formats, and expected transformation behavior work in the application's actual PHP environment.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. spatie/image on GitHub