SimpleImage

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

…

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.

flip($direction)

Flip the image horizontally or vertically.

• $direction* (string) - The direction to flip: x|y|both

Returns a SimpleImage object.

maxColors($max, $dither)

Reduces the image to a maximum number of colors.

• $max* (int) - The maximum number of colors to use.
• $dither (bool) - Whether or not to use a dithering effect (default true).

Returns a SimpleImage object.

overlay($overlay, $anchor, $opacity, $xOffset, $yOffset)

Place an image on top of the current image.

• $overlay* (string|SimpleImage) - The image to overlay. This can be a filename, a data URI, or a SimpleImage object.
• $anchor (string) - The anchor point: 'center', 'top', 'bottom', 'left', 'right', 'top left', 'top right', 'bottom left', 'bottom right' (default 'center')
• $opacity (float) - The opacity level of the overlay 0-1 (default 1).
• $xOffset (int) - Horizontal offset in pixels (default 0).
• $yOffset (int) - Vertical offset in pixels (default 0).
• $calculateOffsetFromEdge (bool) - Calculate Offset referring to the edges of the image. $xOffset and $yOffset have no effect in center anchor. (default false).

Returns a SimpleImage object.

resize($width, $height)

Resize an image to the specified dimensions. If only one dimension is specified, the image will be resized proportionally.

• $width* (int) - The new image width.
• $height* (int) - The new image height.

Returns a SimpleImage object.

resolution($res_x, $res_y)

Changes the resolution (DPI) of an image.

• $res_x* (int) - The horizontal resolution, in DPI.
• $res_y (int) - The vertical resolution, in DPI.

Returns a SimpleImage object.

rotate($angle, $backgroundColor)

Rotates the image.

• $angle* (int) - The angle of rotation (-360 - 360).
• $backgroundColor (string|array) - The background color to use for the uncovered zone area after rotation (default 'transparent').

Returns a SimpleImage object.

text($text, $options, &$boundary)

Adds text to the image.

• $text* (string) - The desired text.
• $options (array) - An array of options.
  • fontFile* (string) - The TrueType (or compatible) font file to use.
  • size (int) - The size of the font in pixels (default 12).
  • color (string|array) - The text color (default black).
  • anchor (string) - The anchor point: 'center', 'top', 'bottom', 'left', 'right', 'top left', 'top right', 'bottom left', 'bottom right' (default 'center').
  • xOffset (int) - The horizontal offset in pixels (default 0).
  • yOffset (int) - The vertical offset in pixels (default 0).
  • shadow (array) - Text shadow params.
    • x* (int) - Horizontal offset in pixels.
    • y* (int) - Vertical offset in pixels.
    • color* (string|array) - The text shadow color.
  • calculateOffsetFromEdge (bool) - Calculate Offset referring to the edges of the image (