README

An ImageMagick "exec" component for PHP apps.

Installation

Install with Composer, it's the best packages manager you can have :

composer require orbitale/imagemagick-php

Requirements

PHP 7.2 or higher
ImageMagick 7 has to be installed on your server, and the binaries must be executable by the user running the PHP process.

Settings

There are not many settings, but when you instantiate a new Command object, you may specify ImageMagick's executable directory directly in the constructor, for example :

use Orbitale\Component\ImageMagick\Command;

// Default directory for many Linux distributions
$command = new Command('/usr/bin/magick');

// Or in Windows, depending of the install directory
$command = new Command('C:\ImageMagick\magick.exe');

// Will try to automatically discover the path of ImageMagick in your system
// Note: it uses Symfony's ExecutableFinder to find it in $PATH
$command = new Command();

The constructor will automatically search for the magick executable, test it, and throw an exception if it's not available.

⚠️ Make sure your ImageMagick binary is executable.

Usage

First, we recommend you to note all possible scripts that you can use with ImageMagick in the official docs:

These correspond to the "legacy binaries", and you can use them if you are familiar or comfortable with them.

As of ImageMagick 7, these are not mandatory, but this package is compatible with them.

Basic image type converter with ImageMagick's basic logo

Read the comments :

require_once 'vendor/autoload.php';

use Orbitale\Component\ImageMagick\Command;

// Create a new command
$command = new Command();

$response = $command
    // The command will search for the "logo.png" file. If it does not exist, it will throw an exception.
    // If it does, it will create a new command with this source image.
    ->convert('logo.png')

    // The "output()" method will append "logo.gif" at the end of the command-line instruction as a filename.
    // This way, we can continue writing our command without appending "logo.gif" ourselves.
    ->output('logo.gif')

    // At this time, the command shall look like this :
    // $ "{ImageMagickPath}convert" "logo.png" "logo.gif"

    // Then we run the command by using "exec()" to get the CommandResponse
    ->run()
;

// Check if the command failed and get the error if needed
if ($response->hasFailed()) {
    throw new Exception('An error occurred:'.$response->getError());
} else {
    // If it has not failed, then we simply send it to the buffer
    header('Content-type: image/gif');
    echo file_get_contents('logo.gif');
}

Resizing an image

require_once 'vendor/autoload.php';

use Orbitale\Component\ImageMagick\Command;

// Create a new command
$command = new Command();

$response = $command

    ->convert('background.jpeg')
    
    // We'll use the same output as the input, therefore will overwrite the source file after resizing it.
    ->output('background.jpeg')

    // The "resize" method allows you to add a "Geometry" operation.
    // It must fit to the "Geometry" parameters in the ImageMagick official documentation (see links below & phpdoc)
    ->resize('50x50')

    ->run()
;

// Check if the command failed and get the error if needed
if ($response->hasFailed()) {
    throw new Exception('An error occurred:'.$response->getError());
} else {
    // If it has not failed, then we simply send it to the buffer
    header('Content-type: image/gif');
    echo file_get_contents('logo.gif');
}

Currently supported options:

There are a lot of command-line options, and each have its own validation system.

This is why a "few" ones are implemented now, to make sure validation is possible for each of them.

Note: If an option is not implemented in the Command class, you can create an issue or make a Pull Request that implements the new option!

Feel free to ask/create an issue if you need more!

Some aliases that do magic for you:

$command->text(): This method uses multiple options added to the -annotate one to generate a text block. You must specify its position and size, but you can specify color and the font file used.
$command->ellipse(): (check source code for the heavy prototype!) This method uses the -stroke, -fill and -draw options to create an ellipse/circle/disc on your picture. Note: I recommend to check both the source code and the documentation to be sure of what you are doing.

Useful links

ImageMagick official website: http://www.imagemagick.org
ImageMagick documentation:
- Installation of the binaries (depending on your OS and/or distribution)
- Geometry option (to resize or place text)
- All command-line options ; they're not all available in this tool for now, so feel free to make a PR ! ;)

orbitale / imagemagick-php

Maintainers

Details