Download the PHP package peterujah/nano-image without Composer

NanoImage

A lightweight PHP library for everyday image manipulation.
Resize, crop, rotate, filter, convert, and save images with a simple, dependency-free API powered by PHP's GD extension.

Overview

NanoImage is a lightweight PHP image library built on the GD extension. It provides common image operations, including resizing, cropping, rotating, applying filters, and converting between supported formats.

Images can be displayed directly, returned as binary data, or saved to a file. NanoImage also handles transparency, supports safe file saving, and checks which image formats are available in the current GD installation.

Features

Requirements

Requires PHP and the GD extension. Support for individual image formats depends on the installed PHP and GD build.

Supported Image Formats

See Supported Formats for format detection and runtime availability details.

Installation

Quick start

Loading

Loading a new image replaces (and frees) the previous one. Images that would not fit in PHP's memory_limit are rejected up front with an UnsupportedImageException instead of crashing PHP.

Resizing

• Sizes must be greater than 0; enlarging is allowed.
• With the ratio option the output is fitted inside the box, so one side can be smaller than requested.
• The THUMBNAIL file name uses the box you passed to resize() (photo-200x200.jpg), even when the ratio option made the actual image smaller.

Cropping, rotating and flipping

Rotating by a multiple of 90 degrees keeps every pixel. Other angles enlarge the canvas; with no background colour the corners are transparent (and saved white for JPEG/BMP).

Filters and blur

If GD rejects a queued filter (an unknown constant or missing arguments), the save fails and returns false; nothing is written.

contrast() flips GD's inverted sign for you. The raw filter(IMG_FILTER_CONTRAST, ...) does not. blur($range, $argument): $range is the number of blur passes; $argument is kept only for backward compatibility and has no effect, because GD's Gaussian blur takes no strength value. Blurred images come out slightly brighter (the original smoothing step adds brightness).

Output

The output format follows the extension you save to (save()) or the extension you pass (saveAs()). toString(), get() and display() use the source image's format.

Save options

• save() and saveAs() create missing directories.
• A path with no extension keeps the source format and gets its extension appended.
• An unsupported extension (or a format your GD cannot write) makes the method return false.
• quality is 0-100. JPEG/WebP/AVIF use it as lossy quality; PNG maps it to the compression level (still lossless); GIF and BMP ignore it. save() defaults to 100, saveAs() and replace() to 90.

Supported formats

Check what your server supports with print_r(gd_info());. A format GD cannot decode throws UnsupportedImageException when loading; one it cannot encode makes the save return false.

Metadata (EXIF)

GD never copies metadata into the images it writes, so every saved image is already stripped; removeExif() is simply a clearly named shortcut for save($path, NanoImage::DEFAULT, 100).

addExif() and setExif() need an exif_write_data() function, which standard PHP does not provide. Without one they return false and save nothing.

Method reference

Constants: JPG, JPEG, PNG, GIF, WEBP, BMP, AVIF, DEFAULT, THUMBNAIL, TIMESTAMP, FLIP_HORIZONTAL, FLIP_VERTICAL, FLIP_BOTH.

How It Works

• Loading: open(), load(), and the constructor throw UnsupportedImageException if the image cannot be loaded.
• Queued operations: resize(), setWidth(), setHeight(), and filters are queued and applied when the image is output.
• Immediate operations: crop(), scale(), rotate(), flip(), and blur() run immediately. Any pending resize is applied first, so crop coordinates refer to the resized image.
• Output: save(), saveAs(), replace(), toString(), get(), and display() return false on failure, except toString(), which returns an empty string. These methods do not release the image, allowing you to produce multiple outputs from the same instance. Call free() when finished.
• Errors: Invalid arguments, such as non-positive dimensions, out-of-bounds crop coordinates, or invalid colours, throw InvalidArgumentException. Editing without a loaded image throws LogicException. Memory exhaustion or a failed GD operation throws RuntimeException where detected.

Limitations

• The whole image is decoded into memory (about 4 bytes per pixel, plus working copies). Very large images need a suitable memory_limit; the class checks first and fails cleanly rather than crash.
• Animated GIF / WebP: only the first frame is processed.
• GIF output has at most 255 colours and one transparent colour.
• Resizing never crops; use crop() for that. There is no "cover/fill" mode.

Testing