Image Bundle Laravel Package

Getting Started

Resolve the framework question before anything else. This is IntegratedImageBundle — a Symfony bundle, not a Laravel package. There is no extra.laravel.providers, no auto-discovery, no php artisan vendor:publish, no facade. In a Laravel codebase, "day-to-day leverage" means one of two things:

• You are actually running Symfony (or a Symfony-based app such as Ibexa/Sulu/Integrated, given the vendor handle), in which case the bundle slots in normally.
• You are on Laravel and would need a thin bridge (a Laravel service provider that binds the bundle's core services, plus hand-wired config). That is real work and should be justified by a spike, not assumed.

Open the repo and read these files in this exact order before installing anything:

Registration (Symfony). There is almost certainly no Flex recipe. Register manually:

// config/bundles.php
return [
    // ...
    Integrated\Bundle\ImageBundle\IntegratedImageBundle::class => ['all' => true],
];

Then inspect what you actually got:

bin/console cache:clear
bin/console config:dump-reference integrated_image   # adjust bundle alias to match
bin/console debug:container --tag=integrated_image.filter
bin/console debug:twig | grep -i image

First use case — one file, one transform, no pipeline. Do not start with responsive variants, WebP conversion and a CDN. Pick a single image already sitting in public/uploads/, push it through the smallest possible transform (one resize, one crop), and verify byte output and cache behavior. That single round-trip exercises the config schema, the imaging engine, the storage adapter and the cache layer at once — if any of those is broken, you want to know in hour one, not week two.

Implementation Patterns

Profile-driven transforms. The bundle's selling point is centralizing transformations behind named profiles. Define profiles once (e.g., thumbnail, hero, avatar) in config rather than sprinkling resize calls through controllers. Treat the config block as your design surface, not an afterthought — it is the thing you will iterate on.

# Illustrative only — confirm keys against config:dump-reference
integrated_image:
    profiles:
        thumbnail:
            transformations:
                - { type: resize, width: 200, height: 200, mode: crop }
        hero:
            transformations:
                - { type: resize, width: 1600, mode: max }
                - { type: convert, format: webp, quality: 82 }

Inject the manager, not the pieces. Controllers and services should depend on the bundle's image/filter manager, not on individual processors. That gives you a single seam to swap later.

Template output through helpers. The bundle ships Twig helpers for responsive image markup. Use them for the <img srcset> loop so templates stay declarative, but read the helper source — helper output is usually where hardcoded paths, HTML attributes and cache-busting logic hide, and that is what you will need to override for a CDN.

Route storage through a Flysystem disk. The critical pattern is that the bundle consumes a filesystem abstraction, not raw local paths. If it hardcodes public/ or absolute paths, it will not survive a move to S3/Spaces, and every transform URL in your DB becomes dead. Confirm this in the storage adapter interface before adoption.

Wrap it behind your own contract. Even in a healthy spike, bind an internal ImageProcessor interface (resize, crop, convert, optimize) and have the bundle satisfy it, with an Intervention Image fallback:

interface ImageProcessor
{
    public function transform(string $source, string $output, array $profile): void;
}

final class BundleImageProcessor implements ImageProcessor { /* delegates to the bundle */ }
final class InterventionImageProcessor implements ImageProcessor { /* fallback */ }

This costs roughly a day and turns an unmaintained dependency into a swappable detail rather than an architectural commitment.

Snapshot-test the output. Because there are no upstream tests, your test suite is the only verification. Hash or byte-compare a fixture image through each profile and assert against a committed baseline. Any fork rebase or config change that silently shifts quality or format will fail the build instead of shipping.

Offload heavy transforms. On-request generation trades CPU for storage. For large images or high-volume paths, dispatch transform jobs to a queue and pre-warm the cache — this is the difference between a p95 that holds under load and one that does not.

Kill switch. Put the whole pipeline behind a config flag so a bad cache-key change or a broken transform can be disabled in one deploy without a code revert.

Gotchas and Tips

The Symfony-in-Laravel trap is the biggest gotcha. No extra.laravel block means Laravel's package auto-discovery will silently ignore it. There is no publishable config, no facade, no artisan command, and the bundle's DI extension passes and YAML service definitions do not exist in Laravel. Budget a day for a bridge provider (bind the manager, hand-map the config schema to a Laravel config file, wire the storage adapter to Storage::disk()) — and only if the spike has already proven value.

ext-gd vs ext-imagick across environments. This is the single most common "works locally, fails in CI/prod" cause with image packages. Check every container image and CI runner. Imagick behavior differs from GD on EXIF orientation, color profiles and WebP quality — pin the engine explicitly.

Memory and hostile input. Confirm whether the bundle streams or loads full images into memory. If it loads, cap upload dimensions and file size upstream and set a memory_limit guard — a single decompression bomb will 502 the worker. Also confirm EXIF stripping, EXIF orientation handling and SVG sanitization; a zero-adoption package is unlikely to have hardened these for you.

Cache invalidation is on you. Editing a profile's dimensions does not automatically invalidate derivatives already written to disk. Expect stale files until you purge. Design the derivative cache key to include the profile definition (or a version hash) so a profile bump produces new keys rather than silently serving old sizes.

Storage growth is unbounded by default. Every width/format combination is a file. Set a TTL or a nightly sweep, and monitor disk usage — this is a recurring ops cost, not a one-off.

Service overrides by ID. The extension points live in Resources/config/services.*. To customize a processor or storage backend, decorate the service by ID or override the parameter, rather than editing the vendor directory. Note the exact IDs you override — they are effectively an undocumented API contract and will change on any upstream rebase.

Pin to a commit SHA, fork, and vendor. With 0 stars and 0 dependents there is no patch stream for CVEs, PHP deprecations, or Symfony major-version drift — and no issue history to search when something breaks. Pin a commit hash in composer.json (not ^1.0 or dev-main), fork under your org, and assign an owner. Ramp-up on the source is roughly a day of reading before any production change, because every behavior must be discovered empirically rather than read from docs.

Watch for path traversal and SSRF. If the bundle exposes any transform route that accepts a user-supplied path or URL, validate that the resolved path stays inside the storage root and that remote URLs are allowlisted before fetching. This class of bug is exactly what a security review would find in unvetted code — do it yourself first.

Two debugging handles to reach for first. debug:container on the image-related service IDs to see what is actually wired, and config:dump-reference to see the schema the extension thinks it has — mismatches between what you wrote in YAML and what the extension parsed are the most common source of silent no-ops.

Default posture: spike, don't adopt. Timebox the evaluation to half a day of source reading. If it does not clearly beat Intervention Image + a Flysystem disk (or a managed service like imgix/Cloudflare Images) on capability, stop — the burden of proof sits entirely with a package that has no adoption signal.