SimpleImage

A PHP class that makes working with images as simple as possible.

Developed and maintained by Cory LaViska.

If this project has you loving PHP image manipulation again, please consider sponsoring me to support its development.

---

Overview

<?php
try {
  // Create a new SimpleImage object
  $image = new \claviska\SimpleImage();

  // Magic! ✨
  $image
    ->fromFile('image.jpg')                     // load image.jpg
    ->autoOrient()                              // adjust orientation based on exif data
    ->resize(320, 200)                          // resize to 320x200 pixels
    ->flip('x')                                 // flip horizontally
    ->colorize('DarkBlue')                      // tint dark blue
    ->border('black', 10)                       // add a 10 pixel black border
    ->overlay('watermark.png', 'bottom right')  // add a watermark image
    ->toFile('new-image.png', 'image/png')      // convert to PNG and save a copy to new-image.png
    ->toScreen();                               // output to the screen

  // And much more! 💪
} catch(Exception $err) {
  // Handle errors
  echo $err->getMessage();
}

Requirements

• PHP 8.0+
• GD extension

For PHP versions below 7.0, please use SimpleImage v3.7.2

Features

• Supports reading, writing, and converting GIF, JPEG, PNG, WEBP, BMP, AVIF formats.
• Reads and writes files, data URIs, and image strings.
• Manipulation: crop, resize, overlay/watermark, adding TTF text
• Drawing: arc, border, dot, ellipse, line, polygon, rectangle, rounded rectangle
• Filters: blur, brighten, colorize, contrast, darken, desaturate, edge detect, emboss, invert, opacity, pixelate, sepia, sharpen, sketch
• Utilities: color adjustment, darken/lighten color, extract colors
• Properties: exif data, height/width, mime type, orientation
• Color arguments can be passed in as any CSS color (e.g. LightBlue), a hex color, or an RGB(A) array.
• Support for alpha-transparency (GIF, PNG, WEBP, AVIF)
• Chainable methods
• Uses exceptions
• Load with Composer or manually (just one file)
• Semantic Versioning

Installation

Install with Composer:

composer require claviska/simpleimage

Or include the library manually:

<?php
require 'src/claviska/SimpleImage.php';

About

SimpleImage is developed and maintained by Cory LaViska. Copyright A Beautiful Site, LLC.

If you enjoy using SimpleImage, especially in commercial applications, please consider sponsoring me to support its development.

Thanks! 🙌

License

Licensed under the MIT license.

API

Order of awesomeness:

1. Load an image
2. Manipulate the image
3. Save/output the image

API tips:

• An asterisk denotes a required argument.
• Methods that return a SimpleImage object are chainable.
• You can pass a file or data URI to the constructor to avoid calling fromFile or fromDataUri.
• Static methods can be called with $image::methodName() or \claviska\SimpleImage::methodName().
• Colors can be a CSS color (e.g. white), a hex string (e.g. '#ffffff'), or an RGBA array.
• You can pipe transparency to normalizeColor when you pass a CSS color or hex string: white|0.25

Loaders

fromDataUri($uri)

Loads an image from a data URI.

• $uri* (string) - A data URI.

Returns a SimpleImage object.

fromFile($file)

Loads an image from a file.

• $file* (string) - The image file to load.

Returns a SimpleImage object.

fromNew($width, $height, $color)

Creates a new image.

• $width* (int) - The width of the image.
• $height* (int) - The height of the image.
• $color (string|array) - Optional fill color for the new image (default 'transparent').

Returns a SimpleImage object.

fromString($string)

Creates a new image from a string.

• $string* (string) - The raw image data as a string. Example:

  $string = file_get_contents('image.jpg');
  

Returns a SimpleImage object.

Savers

toDataUri($mimeType, $options)

Generates a data URI.

• $mimeType (string) - The image format to output as a mime type (defaults to the original mime type).
• $options (array|int) - Array of options or Image quality as a percentage (default 100).

Returns a string containing a data URI.

toDownload($filename, $mimeType, $options)

Forces the image to be downloaded to the clients machine. Must be called before any output is sent to the screen.

• $filename* (string) - The filename (without path) to send to the client (e.g. 'image.jpeg').
• $mimeType (string) - The image format to output as a mime type (defaults to the original mime type).
• $options (array|int) - Array of options or Image quality as a percentage (default 100).

Returns a SimpleImage object.

toFile($file, $mimeType, $options)

Writes the image to a file.

• $mimeType (string) - The image format to output as a mime type (defaults to the original mime type).
• $options (array|int) - Array of options or Image quality as a percentage (default 100).

Returns a SimpleImage object.

toScreen($mimeType, $options)

Outputs the image to the screen. Must be called before any output is sent to the screen.

• $mimeType (string) - The image format to output as a mime type (defaults to the original mime type).
• $options (array|int) - Array of options or Image quality as a percentage (default 100).

Returns a SimpleImage object.

toString($mimeType, $options)

Generates an image string.

• $mimeType (string) - The image format to output as a mime type (defaults to the original mime type).
• $options (array|int) - Array of options or Image quality as a percentage (default 100).

Returns a SimpleImage object.

generate($mimeType, $options)

Generates an image.

• $mimeType (string) - The image format to output as a mime type (defaults to the original mime type).
• $options (array|int) - Array of options or Image quality as a percentage (default 100).

Returns an array: [mimeType, data]

Options array

Instead of providing the quality as an integer as the last function parameter you can also set various options depending on the targeted Mime type using an associative array.

$image->toFile($file, 'image/avif', [
    // JPG, WEBP, AVIF (default 100)
    'quality' => 100,

    // AVIF (default -1 which is 6)
    // range of slow and small file 0 to 10 fast but big file
    'speed' => -1,
]);

$image->toFile($file, 'image/bmp', [
    // BMP: boolean (default true)
    'compression' => true,

    // BMP, JPG (default null, keep the same)
    'interlace' => null,
]);

$image->toFile($file, 'image/gif', [
    // GIF, PNG (default true)
    'alpha' => true,
]);

$image->toFile($file, 'image/jpeg', [
    // BMP, JPG (default null, keep the same)
    'interlace' => null,

    // JPG, WEBP, AVIF (default 100)
    'quality' => 100,
]);

$image->toFile($file, 'image/png', [
    // GIF, PNG (default true)
    'alpha' => true,

    // PNG: 0-10, defaults to zlib (default 6)
    'compression' => -1,

    // PNG (default -1)
    'filters' => -1,

    // has no effect on PNG images, since the format is lossless
    // 'quality' => 100,
]);

$image->toFile($file, 'image/webp', [
    // JPG, WEBP, AVIF (default 100)
    'quality' => 100,
]);

Utilities

getAspectRatio()

Gets the image's current aspect ratio.

Returns the aspect ratio as a float.

getExif()

Gets the image's exif data.

Returns an array of exif data or null if no data is available.

getHeight()

Gets the image's current height.

Returns the height as an integer.

getMimeType()

Gets the mime type of the loaded image.

Returns a mime type string.

getOrientation()

Gets the image's current orientation.

Returns a string: 'landscape', 'portrait', or 'square'

getResolution()

Gets the image's current resolution in DPI.

Returns an array of integers: [0 => 96, 1 => 96]

getWidth()

Gets the image's current width.

Returns the width as an integer.

hasImage()

Checks if the SimpleImage object has loaded an image.

Returns a boolean.

reset()

[!NOTE]
The reset() method has been deprecated in SimpleImage 4.4.0. Calling the method has no effect.

Destroys the image resource.

Returns a SimpleImage object.

Manipulation

autoOrient()

Rotates an image so the orientation will be correct based on its exif data. It is safe to call this method on images that don't have exif data (no changes will be made). Returns a SimpleImage object.

bestFit($maxWidth, $maxHeight)

Proportionally resize the image to fit inside a specific width and height.

• $maxWidth* (int) - The maximum width the image can be.
• $maxHeight* (int) - The maximum height the image can be.

Returns a SimpleImage object.

crop($x1, $y1, $x2, $y2)

Crop the image.

• $x1 - Top left x coordinate.
• $y1 - Top left y coordinate.
• $x2 - Bottom right x coordinate.
• $y2 - Bottom right x coordinate.

Returns a SimpleImage object.

fitToHeight($height) (DEPRECATED)

Proportionally resize the image to a specific height.

This method was deprecated in version 3.2.2 and will be removed in version 4.0. Please use resize(null, $height) instead.

• $height* (int) - The height to resize the image to.

Returns a SimpleImage object.

fitToWidth($width) (DEPRECATED)

Proportionally resize the image to a specific width.

This method was deprecated in version 3.2.2 and will be removed in version 4.0. Please use resize($width, null) instead.

• $width* (int) - The width to resize the image to.

Returns a SimpleImage object