Top Related Projects
PHP Object Oriented image manipulation library
Manipulate images with an expressive API
A PHP class that makes working with images and GD as simple as possible.
A PHP library to handle images
Wonderfully easy on-demand image manipulation library with an HTTP based API.
Quick Overview
The Imagine library is a PHP image manipulation library that provides a unified API to work with images using different image processing libraries such as GD, Imagick, and Gmagick. It allows developers to perform various image manipulation tasks such as resizing, cropping, filtering, and more, with a consistent and easy-to-use interface.
Pros
- Consistent API: The library provides a consistent API across different image processing libraries, making it easy to switch between them without having to rewrite your code.
- Flexibility: Imagine supports a wide range of image formats, including JPEG, PNG, GIF, BMP, TIFF, and WebP, allowing you to work with a variety of image types.
- Extensibility: The library is designed to be extensible, allowing developers to create their own custom filters and effects.
- Performance: Imagine is optimized for performance, with support for lazy loading and efficient memory management.
Cons
- Dependency on external libraries: Imagine requires the installation of one of the supported image processing libraries (GD, Imagick, or Gmagick), which can add complexity to the setup process.
- Limited documentation: The documentation for Imagine could be more comprehensive, making it harder for new users to get started with the library.
- Potential version compatibility issues: As with any library, there may be compatibility issues when upgrading to newer versions, which could require changes to your codebase.
- Limited support for advanced image manipulation: While Imagine provides a wide range of basic image manipulation features, it may not be as well-suited for more complex or specialized image processing tasks.
Code Examples
Here are a few examples of how to use the Imagine library:
- Resizing an image:
use Imagine\Image\ManipulatorInterface;
use Imagine\Gd\Imagine;
$imagine = new Imagine();
$image = $imagine->open('image.jpg');
$image->resize(new \Imagine\Image\Box(300, 200), ManipulatorInterface::FILTER_LANCZOS)
->save('resized_image.jpg');
- Cropping an image:
use Imagine\Image\Box;
use Imagine\Image\Point;
use Imagine\Gd\Imagine;
$imagine = new Imagine();
$image = $imagine->open('image.jpg');
$image->crop(new Point(100, 100), new Box(200, 150))
->save('cropped_image.jpg');
- Applying a grayscale filter:
use Imagine\Filter\Basic\Grayscale;
use Imagine\Gd\Imagine;
$imagine = new Imagine();
$image = $imagine->open('image.jpg');
$image->apply(new Grayscale())
->save('grayscale_image.jpg');
- Overlaying an image:
use Imagine\Image\Box;
use Imagine\Image\Point;
use Imagine\Gd\Imagine;
$imagine = new Imagine();
$image = $imagine->open('background.jpg');
$watermark = $imagine->open('watermark.png');
$image->paste($watermark, new Point(10, 10))
->save('image_with_watermark.jpg');
Getting Started
To get started with the Imagine library, follow these steps:
- Install the library using Composer:
composer require imagine/imagine
- Import the necessary classes and create an instance of the
Imagine
class:
use Imagine\Gd\Imagine;
$imagine = new Imagine();
- Open an image and perform the desired manipulations:
$image = $imagine->open('image.jpg');
$image->resize(new \Imagine\Image\Box(300, 200), ManipulatorInterface::FILTER_LANCZOS)
->save('resized_image.jpg');
- Explore the available filters and effects provided by the library, and customize your image processing workflow as needed.
Competitor Comparisons
PHP Object Oriented image manipulation library
Pros of Imagine
- Well-established and widely used image manipulation library for PHP
- Supports various image formats and operations like resize, crop, and filters
- Actively maintained with regular updates and bug fixes
Cons of Imagine
- May have a steeper learning curve for beginners
- Some advanced features might require additional dependencies
Code Comparison
Both repositories are the same project, so there's no code comparison to be made. Here's a sample of how to use Imagine:
use Imagine\Gd\Imagine;
use Imagine\Image\Box;
$imagine = new Imagine();
$image = $imagine->open('path/to/image.jpg');
$image->resize(new Box(800, 600))
->save('path/to/resized_image.jpg');
Additional Notes
It's important to note that php-imagine/Imagine and php-imagine/Imagine> appear to be the same repository. The difference in the name might be due to a typo or formatting issue. Imagine is a single, unified image manipulation library for PHP, and there aren't two separate versions to compare.
The library provides a powerful and flexible API for image manipulation tasks, making it a popular choice among PHP developers for handling image-related operations in their projects.
Manipulate images with an expressive API
Pros of Image
- Simpler API with a more fluent interface for common image operations
- Built-in support for responsive images and image optimization
- Better integration with Laravel framework
Cons of Image
- Less extensive manipulation capabilities compared to Imagine
- Fewer supported image formats and drivers
- Smaller community and ecosystem
Code Comparison
Image:
Image::load('image.jpg')
->crop(Manipulations::CROP_CENTER, 100, 100)
->blur(50)
->save();
Imagine:
$imagine = new Imagine\Gd\Imagine();
$image = $imagine->open('image.jpg');
$image->crop(new Point(0, 0), new Box(100, 100))
->effects()->blur(50);
$image->save('image.jpg');
Summary
Image offers a more straightforward API and better Laravel integration, making it ideal for common image operations in Laravel projects. However, Imagine provides more extensive manipulation capabilities and supports a wider range of image formats, making it more suitable for complex image processing tasks across different PHP frameworks. The choice between the two depends on the specific project requirements and the developer's familiarity with Laravel.
A PHP class that makes working with images and GD as simple as possible.
Pros of SimpleImage
- Lightweight and easy to use, with a simple API for common image manipulation tasks
- No external dependencies, making it easier to integrate into projects
- Supports basic operations like resizing, cropping, and filters out of the box
Cons of SimpleImage
- Limited advanced features compared to Imagine's extensive capabilities
- Less flexibility for complex image processing tasks
- Smaller community and fewer updates
Code Comparison
SimpleImage:
$image = new \claviska\SimpleImage();
$image
->fromFile('image.jpg')
->resize(300, 200)
->toFile('resized.jpg');
Imagine:
$imagine = new Imagine\Gd\Imagine();
$size = new Imagine\Image\Box(300, 200);
$imagine->open('image.jpg')
->resize($size)
->save('resized.jpg');
Summary
SimpleImage is a lightweight, easy-to-use library for basic image manipulation tasks, while Imagine offers more advanced features and flexibility. SimpleImage is ideal for simple projects with straightforward image processing needs, whereas Imagine is better suited for complex applications requiring extensive image manipulation capabilities. The choice between the two depends on the specific requirements of your project and the level of image processing complexity you need to handle.
A PHP library to handle images
Pros of Image
- Simpler API with a more intuitive interface for basic image manipulation tasks
- Built-in caching mechanism for improved performance
- Supports image opening from URLs out of the box
Cons of Image
- Less comprehensive feature set compared to Imagine
- Limited support for advanced image processing operations
- Smaller community and fewer updates
Code Comparison
Image:
$image = Image::open('image.jpg')
->resize(100, 100)
->negate()
->save('output.jpg');
Imagine:
$imagine = new Imagine\Gd\Imagine();
$image = $imagine->open('image.jpg');
$image->resize(new Box(100, 100))
->effects()->negative();
$image->save('output.jpg');
Both libraries provide methods for basic image manipulation, but Imagine offers a more object-oriented approach with separate classes for different operations. Image, on the other hand, uses method chaining for a more concise syntax.
While Image is easier to use for simple tasks, Imagine provides more flexibility and advanced features for complex image processing needs. The choice between the two depends on the specific requirements of your project and the level of control you need over image manipulation operations.
Wonderfully easy on-demand image manipulation library with an HTTP based API.
Pros of Glide
- Focused on image manipulation and serving, with built-in HTTP caching and security features
- Offers a simple URL-based API for image transformations
- Provides easy integration with various storage systems (local, S3, etc.)
Cons of Glide
- Less flexible for complex image processing tasks compared to Imagine
- Limited to predefined image manipulations, while Imagine allows for more custom operations
- Requires additional setup for server configuration to handle image requests
Code Comparison
Glide:
$server = League\Glide\ServerFactory::create([
'source' => 'path/to/source/folder',
'cache' => 'path/to/cache/folder',
]);
$server->outputImage('image.jpg', ['w' => 300, 'h' => 200]);
Imagine:
$imagine = new Imagine\Gd\Imagine();
$image = $imagine->open('image.jpg');
$image->resize(new Imagine\Image\Box(300, 200))
->save('resized_image.jpg');
Summary
Glide excels in serving and manipulating images on-the-fly with a simple URL-based API, making it ideal for web applications that require dynamic image resizing and transformations. It also offers built-in security features and caching.
Imagine, on the other hand, provides a more flexible and powerful toolkit for image manipulation, allowing for complex operations and custom processing. It's better suited for applications that require advanced image editing capabilities beyond simple resizing and transformations.
Choose Glide for quick, web-focused image serving and basic manipulations, or Imagine for more complex, programmatic image processing tasks.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Imagine
Tweet about it using the #php_imagine hashtag.
Image manipulation library for PHP inspired by Python's PIL and other image libraries.
Requirements
The Imagine library has the following requirements:
- PHP 5.5+
Depending on the chosen Image implementation, you may need one of the following PHP extensions:
- GD2
- Imagick (with ImageMagick version 6.2.9 or later, except version 7.0.7-32)
- Gmagick
To read EXIF metadata (e.g. for autorotation), activate the PHP exif
extension. This is optional: Imagine works
without the PHP exif
extension, but then it can't read and act on image orientation or other EXIF metadata.
Installation using composer
php composer.phar require imagine/imagine
Basic Principles
The main purpose of Imagine is to provide all the necessary functionality to bring all native low level image processing libraries in PHP to the same simple and intuitive OO API.
Several things are necessary to accomplish that:
- Image manipulation tools, such as resize, crop, etc.
- Drawing API - to create basic shapes and advanced charts, write text on the image
- Masking functionality - ability to apply black&white or grayscale images as masks, leading to semi-transparency or absolute transparency of the image the mask is being applied to
The above tools should be the basic foundation for a more powerful set of tools that are called Filters
in Imagine.
Some of the ideas for upcoming filters:
- Charting and graphing filters - pie and bar charts, linear graphs with annotations
- Reflection - apple style
- Rounded corners - web 2.0
Documentation
Presentations
Articles
Contributing
Branches
New pull requests should be based on the develop
branch.
The master
branch is the stable branch: it usually matches the latest a release but in can be a bit ahead.
Test groups
Some PHPUnit test is marked as skipped (for example, tests that require a driver that support multiple layers and executed with the GD driver). In addition, if you don't have installed gmagick, the gmagick tests will be marked as skipped.
If you don't want to run tests that are marked as "always skipped" you can tell PHPUnit to exclude the always-skipped
group.
The same for the tests that require a specific driver (gd
, imagick
, imagick
).
So, for example, to exclude the always-skipped
and the gmagick
tests, you can launch phpunit with this command options:
composer run test -- --exclude-group always-skipped,gmagick
Development environment
Setting up an environment with all the required libraries may be very hard. In order to run the tests locally, you can use the same docker images used by Imagine to test the pull requests.
For example, if you have Imagine locally in the /home/me/imagine
folder, you can run tests for PHP 8.1 with the GD and Imagick with this very simple approach:
- Launch a temporary docker container with:
docker run --rm -it -v /home/me/imagine:/app -w /app ghcr.io/php-imagine/test:8.1-gd-imagick bash
- Inside the docker container, run these commands:
# Start a local web server: some tests require it cd tests php -n -S 0.0.0.0:8013 >/dev/null 2>&1 & cd .. # Tell the tests that the local web server is available at the port 8013 export IMAGINE_TEST_WEBSERVERURL=http://localhost:8013 # Install the composer dependencies composer update # Run the tests composer run test -- --exclude-group always-skipped,gmagick
Note: This approach works on Windows too: simply launch the docker container with
docker run --rm -it -v C:\Path\To\Imagine:/app -w /app ghcr.io/php-imagine/test:8.1-gd-imagick bash
Built test files
Many tests create temporary files (in the tests/tmp
directory) containing built images.
Those temporary files are compared with expected images, and then are deleted.
If you want to keep those temporary files (for example, to check what's being built), you can set the IMAGINE_TEST_KEEP_TEMPFILES
environment variable.
If the IMAGINE_TEST_KEEP_TEMPFILES
is configured in the GitHub Action tests, those temporary files are attached to tests as an articact.
Top Related Projects
PHP Object Oriented image manipulation library
Manipulate images with an expressive API
A PHP class that makes working with images and GD as simple as possible.
A PHP library to handle images
Wonderfully easy on-demand image manipulation library with an HTTP based API.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot