Symfony2 Image Manager Laravel Package

Getting Started

Frame the decision before you write code. hoyes/symfony2-image-manager is a Symfony2 bundle, not a Laravel package. There is a DependencyInjection/Extension class where a Laravel package would have a ServiceProvider, a Configuration tree where it would have config/*.php, and Twig helpers where it would have Blade directives. composer require into a Laravel 10/11 app will not produce a working install — at best it resolves and sits inert, at worst its symfony/* constraints conflict with your framework pins. So "getting started" for a Laravel developer means read it, then port the useful parts into a first-party service — not adopt it.

Where to look first, in this order (budget half a day):

1. DependencyInjection/<Name>Extension.php and Configuration.php — the real API surface. The config tree tells you what knobs exist (storage path, web root, adapter, default filter dimensions).
2. Resources/config/services.xml — the concrete service definition: the class name behind the manager, what it injects (a path? @filesystem? an adapter?), and the service ID you'd otherwise type-hint.
3. The manager/service class itself — look specifically for where the resizing actually happens. If it's five lines calling Imagick::resizeImage() or imagecopyresampled(), the bundle has no transferable value and you stop here. If it contains a filter DSL, cache-key strategy, or derivative-path scheme, that's the salvage.
4. Resources/doc/ or README.md — usually a short YAML snippet plus a controller example; read the controller example to understand the intended call sequence (upload → transform → persist → render).
5. composer.json — PHP/Symfony pins. Assume PHP 5.6/Symfony 2.7-era. Expect code that fatals on PHP 8 (each(), create_function, un-parenthesized ternaries, missing return types).

Your first use case in Laravel is not "use the package," it's "replace it." The realistic day-one task is: take one feature the bundle provided (upload + thumbnail + cached URL) and implement it as a Laravel ImageManager contract bound in a service provider, using intervention/image for manipulation and Storage for persistence. The bundle serves as a checklist of behaviour to preserve, not a dependency.

composer require intervention/image
php artisan make:provider ImageServiceProvider

// app/Contracts/ImageManager.php
interface ImageManager {
    public function store(UploadedFile $file, string $disk = 'public'): string;
    public function thumbnail(string $path, int $w, int $h): string;
}

Bind it, resolve FilterConfig, and you have something the bundle was reaching for — with maintained underlying libraries, PHP 8 support, and a service container you already understand.

Implementation Patterns

The extraction pattern (the one you'll actually use). When a legacy Symfony service needs to keep working while the Laravel side is built, don't call across the boundary. Read the Symfony class, reimplement its contract as a first-party class, and run both during cutover. Keep the Symfony bundle untouched and isolated so its config tree doesn't leak into your new config.

Upload handling — mirror the storage contract, not the code. The bundle's "configurable storage paths" almost certainly means a %kernel.root_dir%/../web/uploads style parameter. In Laravel, translate that to a disk rather than a path:

// config/filesystems.php
'disks' => [
    'images' => [
        'driver' => 'local',
        'root'   => storage_path('app/public/images'),
        'url'    => env('APP_URL').'/storage/images',
    ],
],

Store under a content-hash or UUID prefix, never the original filename, and return the relative path so the URL is derivable — this is the pattern that makes derivatives cacheable and safe.

Fluent transform → cached thumbnail pattern. The bundle's "fluent API with cached output" is the shape to preserve in your port: a transform call that returns a derivative path keyed deterministically from (source path, dimensions, filter set). Implement that as:

$key = hash('xxh128', $path.'|thumb|'.$w.'x'.$h.'|v2');
$out = "derivatives/v2/{$key}.jpg";
if (!Storage::disk('images')->exists($out)) {
    Image::read(Storage::disk('images')->path($path))
        ->cover($w, $h)      // cover = crop+resize, matches typical "thumbnail" semantics
        ->save(Storage::disk('images')->path($out));
}
return Storage::disk('images')->url($out);

Version the derivative directory (v2) — bump it when filter definitions change, which is the only reliable cache invalidation story with a dead upstream.

Blade directive in place of Twig helpers. The bundle's Twig helper becomes a small Blade directive plus a URL helper, not a ported Twig extension:

Blade::directive('thumb', fn ($expr) => "<?php echo app(ImageManager::class)->thumbnail({$expr}); ?>");

Keep it thin — directives that call services directly are fine; directives that contain image logic are not.

Queue the transform, serve synchronously from cache. Pattern for "day-to-day": the upload request stores the original and dispatches GenerateThumbnails; the first render hits cache or returns a placeholder; the URL is stable regardless. This matches the bundle's cached-output intent but uses Laravel's queue and storage abstractions instead of Symfony's.

Integration tip for mixed stacks. If the legacy Symfony app and the new Laravel app share the same uploads directory during migration, agree on the derivative path layout before you port. Nothing is harder to unwind than two apps writing uploads/thumbs/ with different key schemes.

Gotchas and Tips

The install trap. composer require may technically succeed while doing nothing useful. Check after install: is there a service provider? There isn't, and there won't be. If your composer.json now carries this in require, remove it — a dead dependency in the lockfile is a maintenance and audit liability even when unloaded.

Bundle ≠ package. Do not attempt to register Symfony bundle services from a Laravel service provider. DependencyInjection\Extension, Bundle::boot(), and the Symfony event dispatcher have no Laravel equivalent; shimming them means loading symfony/dependency-injection and symfony/http-kernel into a process that already has Laravel's container and kernel. That's two DI containers in one request — dependency injection will work, but never predictably, and make()/app() resolution will behave differently depending on which container booted first.

PHP-era code hazards when reading. Expect: no declare(strict_types=1), short-array syntax possibly absent, each()/create_function, get_class() === comparisons, and array-to-string implicit conversions. If you copy snippets, they'll fail static analysis or fatals under PHP 8. Modernise mechanically during the port, not after.

Licensing is a hard gate, not a formality. Before lifting code, confirm there's a LICENSE file and that it permits derivative use. Many zero-star 2013-era bundles ship no license at all — which under default copyright means you cannot legally copy the code. Read first, port second. If the license is unclear, reimplement from behaviour and discard the source.

Filter semantics are the highest risk in the port. "Resize" vs "crop" vs "cover" vs "contain" mean different things per library, and thumbnails generated slightly wrong (1-pixel off, wrong anchor, wrong background fill) look fine until someone notices a month of bad assets. Write golden-file tests against representative inputs: EXIF-rotated JPEG, animated GIF, palette PNG with transparency, oversized upload. There is no upstream test suite to lean on — you are the entire verification story.

Memory and payload limits, enforced before decode. GD/Imagick read the whole image into memory; a 40MP upload can OOM a worker. Get the dimensions from the header first (getimagesize() / Image::read()->width() on a stream), reject over your threshold, and set memory_limit per job. This is not optional for a public upload endpoint, and no archived bundle gives you this by default.

Write atomically, name by content. Partial writes from a killed worker leave truncated JPEGs that serve fine once and break the browser cache forever. Write to path.tmp and rename(); key derivatives by content hash so a re-run is idempotent.

Never key a derivative from user input. If filenames or query strings reach the derivative path, you've built a cache-poisoning and path-traversal vector. Always derive keys from a hash of (source path, normalised filter args, version).

The cache grows superlinearly. Each filter combination is a new file. Define the filter set explicitly (an enum or config array), reject unlisted combinations, and add a reclaim job for orphaned derivatives. Without this you'll discover months of accumulated files and no safe way to garbage-collect them.

No upstream means the CVE is yours. The image library parsing untrusted bytes is your highest-severity surface. intervention/image on top of Imagick keeps you patched; the archived bundle cannot. If the bundle is still live in a legacy Symfony service, isolate it behind a network boundary and restrict what reaches it while you migrate.

Log the decision. If this evaluation ends in "declined," write it down — file it against the dependency-policy doc with the score, archived status, and zero-dependent count. It keeps the same package off the table next quarter, and it's the same signal as the package itself: no community validation means every defect is one you find in production.