Image Conversion Laravel Package

Getting Started

This is the Zeta Components image conversion library — a PHP 5-era package that wraps GD, ImageMagick, and GraphicsMagick behind one API. It is unmaintained (last meaningful release ~2012), has zero dependents, and will not run cleanly on PHP 8 (curly-brace string offsets and other removed syntax). Your first step is to confirm you inherited legacy code rather than choosing this for a new project:

composer require zetacomponents/image-conversion
php -v                              # package targets PHP 5.2–7.x
php -r 'require "vendor/autoload.php"; echo class_exists("ezcImageConverter") ? "ok" : "fail";'

If that fatals or prints fail, stop and migrate to intervention/image or spatie/image — same GD/Imagick backend, supported on modern PHP.

If it loads, the first use case is a named transformation pipeline:

require 'vendor/autoload.php';

$converter = new ezcImageConverter(
    new ezcImageConverterSettings(
        array( new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ) )
    )
);

$converter->createTransformation( 'thumb', array(
    new ezcImageFilter( 'scale', array( ezcImageGeometryFilters::SCALE_BOTH, 200, 200 ) ),
    new ezcImageFilter( 'mime',  array( 'image/jpeg' ) ),
) );

$converter->transform( 'thumb', '/abs/in.png', '/abs/out.jpg' );

Where to look first: src/converter.php, src/handler/gd.php, and src/filters/. The docs/ folder and the tests/ fixtures are more accurate than the README — filter names and constant values are string-based and only discoverable in source.

Implementation Patterns

Named transformations as your pipeline registry. The library's central idea is createTransformation($name, array $filters) once, then transform($name, $src, $dst) many times. Define your pipelines (thumb, hero, avatar) in one place — a Laravel service provider or a config array — rather than scattering ezcImageFilter construction through controllers.

Wrap it in a service. The API is file-path based, not framework-aware. A thin service gives you testability and one place to swap the backend later:

class ImagePipeline
{
    private ezcImageConverter $converter;

    public function __construct()
    {
        $this->converter = new ezcImageConverter(
            new ezcImageConverterSettings([
                new ezcImageHandlerSettings('GD', 'ezcImageGdHandler'),
            ])
        );
        $this->converter->createTransformation('thumb', [
            new ezcImageFilter('scale', [ezcImageGeometryFilters::SCALE_BOTH, 200, 200]),
            new ezcImageFilter('mime',  ['image/jpeg']),
        ]);
    }

    public function thumb(string $in, string $out): void
    {
        $this->converter->transform('thumb', $in, $out);
    }
}

Queue jobs are a natural fit. transform() is stateless per call, so it's safe inside a queued job. Pass the local filesystem path from Storage::path(), not a URL — the handlers shell out or fopen the path directly.

Batch loops: reuse the converter, catch per file. Constructing the converter parses handler settings each time. Build it once, then loop and wrap each transform() in try/catch (ezcImageException $e) so one corrupt upload doesn't abort the batch. Report the exception, skip, continue.

Handler priority as a fallback chain. In ezcImageConverterSettings you pass an ordered list of ezcImageHandlerSettings. If GD lacks an operation (e.g. a colorspace or watermark filter it doesn't implement), the converter falls through to ImageMagick. List GD first for cheap operations, ImageMagick second for capability — but verify the fallback actually works, since the behaviour is per-filter, not per-transformation.

Output format is a filter, not a parameter. Chain the mime filter last (image/jpeg, image/png, image/gif) to control the container. Without it, output format defaults to the source format. After conversion, hand the destination path back to Laravel's Storage to move/finalize.

Test with fixtures, assert properties not bytes. Small PNG/JPEG fixtures, then assert on getimagesize() dimensions and mime type. Byte-for-byte comparisons will be flaky across ImageMagick versions.

Gotchas and Tips

• PHP 8 is a hard stop. Curly-brace string indexing ($str{0}) was removed in 8.0; this codebase predates that. Run it on PHP 7.4 at most, or patch the offending files — there's no upstream to rely on.
• ImageMagick/GraphicsMagick handlers shell out. They require the convert / gm binary on PATH and exec() not disabled. Verify with which convert on the server user, not your shell. Failures surface as a generic "not processable" exception with the CLI stderr buried in the message — log it, don't swallow it.
• GD eats memory on large uploads. ezcImageGdHandler loads the full bitmap. A 5000×5000 JPEG can exceed a default memory_limit. Raise it per job or route large images to ImageMagick.
• Paths must be absolute and the destination directory must exist and be writable. The library won't create directories, and relative watermark paths resolve against the process CWD — always pass absolute paths.
• No WebP or AVIF. This era of the package predates both. Don't expose format choices you can't fulfil; reject or convert externally.
• Transparent PNG → JPEG turns black. There's no implicit flatten in older builds. Pre-flatten or expect a black background behind transparent regions.
• Exception hierarchy is broad. Catch ezcImageException (the base) at the boundary in jobs and controllers; the finer subclasses vary by failure mode and aren't worth enumerating in application code.
• Autoloading is classmap, not PSR-4. Class names are ezc* with no namespace. If you add the package to a modern Laravel app, run composer dump-autoload after install and confirm class_exists('ezcImageConverter'). Splitting filters across files sometimes requires manual require in odd setups.
• Licence metadata says NOASSERTION in tooling, but the source headers are Apache 2.0. Check the LICENSE file before redistributing — the repo's machine-readable metadata is wrong.
• Migrate rather than extend. Six stars, zero dependents, no security fixes since PHP 5. If you're building anything new, intervention/image covers every filter here with a maintained GD/Imagick driver and PHP 8 support. Use this package only to keep legacy code alive while you plan the swap.