Imgix Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no service provider, facade, or Blade integration. If you're working in Laravel, you have two options: (a) use imgix/imgix-php directly in a small service provider + facade, or (b) read this bundle as a reference implementation and copy its ~100 lines of config/Twig glue into Blade directives. Don't try to install it into a Laravel app expecting it to boot.

If you are in Symfony (or evaluating for a Symfony service you maintain):

1. Check constraints before installing. The package has 0 stars and 0 dependents, so treat it as unmaintained until proven otherwise. Open composer.json on GitHub and confirm the symfony/* and php version ranges match your app. Then composer require goldenline/imgix-bundle.

2. Register the bundle — config/bundles.php on Symfony 4+, AppKernel::registerBundles() on older versions.

3. Configure a source: domain (e.g. your-source.imgix.net), HTTPS flag, and signing key if the source is secured. Put the sign key in an env var, never in YAML.

4. Look at two files first: DependencyInjection/Configuration.php (the real config tree — trust it over the README) and the Twig extension (the actual filter/function names it registers). Those two files are ~90% of the bundle's surface area.

5. First use case: you store relative asset paths in the database (products/hero.jpg), and in a template you render an <img> with transformation params:

   <img src="{{ 'products/hero.jpg'|imgix_url({ w: 800, auto: 'format', q: 75 }) }}"
        alt="Hero">
   

   Or, in Laravel with the underlying library directly:

   $builder = new \Imgix\UrlBuilder('your-source.imgix.net');
   $builder->setUseHttps(true);
   $url = $builder->createURL('products/hero.jpg', ['w' => 800, 'auto' => 'format']);
   

Implementation Patterns

Inject the builder, not the container. The bundle exposes an Imgix\UrlBuilder-shaped service. Type-hint that (or the bundle's service ID) in your controllers and domain services.

Wrap it in a preset layer. Raw per-call param arrays scatter magic numbers across templates. Define named presets once:

final class ImageUrlGenerator
{
    private const PRESETS = [
        'thumb'   => ['w' => 200, 'h' => 200, 'fit' => 'crop', 'auto' => 'format'],
        'hero'    => ['w' => 1600, 'auto' => 'format', 'q' => 75],
        'og'      => ['w' => 1200, 'h' => 630, 'fit' => 'crop'],
    ];

    public function __construct(private UrlBuilder $builder) {}

    public function url(string $path, string $preset, array $overrides = []): string
    {
        return $this->builder->createURL($path, self::PRESETS[$preset] + $overrides);
    }
}

Responsive images. Generate srcset from a fixed width ladder and always pair it with sizes. imgix-php has createSrcSet() / createSrcSetPair() — use them rather than hand-rolling string concatenation, and sort/dedupe widths ascending.

Store paths, not URLs. Persisting https://source.imgix.net/foo.jpg?w=800 in the DB bakes your CDN domain and params into your data. Store foo.jpg, generate at render time. Switching domains between staging and prod then becomes a config-only change.

Local/dev fallback. In dev you often have no imgix source. Configure the domain as null and have your generator fall back to asset($path) so the app still renders without network access to imgix.

Test with exact strings. Unit-test the generator with a fixture key and assert full URLs (assertSame). URL-generation bugs are silent — a wrong param just looks like a low-quality image. Snapshot tests catch accidental preset changes.

Extend by decoration. Add defaults (auto=format, q=75) globally by decorating the bundle's builder service with a small class that merges defaults before delegating, instead of editing templates everywhere.

Gotchas and Tips

• Maintenance risk is the headline. Zero dependents and a stale-looking repo mean no security patches and no Symfony 6/7 compatibility guarantees. Pin the exact version, and budget for replacing it — because it's thin glue over imgix-php, that's a half-day job, not a migration.
• No Laravel support. No facade, no Blade, no config publishing, no queue/HTTP integration. The library underneath is framework-agnostic; the bundle is not.
• Signed URLs and caching. The signature covers the path and all params. Changing a default (q, auto) invalidates every previously cached URL at the imgix edge. Expected — just don't do it casually on a high-traffic deploy.
• 403 vs 404 debugging. 403 almost always means signature mismatch (wrong key, or signing enabled on the source but not in config, or vice versa). 404 means domain/path problem. Open the generated URL in the imgix dashboard's preview to isolate which.
• Path encoding. Leading slashes, spaces, and non-ASCII filenames are the most common source of broken images. Pick one convention (store without a leading slash) and normalize in the generator, not in templates.
• HTTPS flag. If use_https is off you'll ship mixed-content images that browsers silently block. Set it explicitly, don't rely on a default.
• srcset ordering. Browsers expect ascending widths; duplicates waste bandwidth. Enforce it in code, not by convention.
• Extension points: Symfony DI decoration or a compiler pass over the bundle's service ID; you can also bypass the bundle entirely and inject Imgix\UrlBuilder yourself — the bundle adds convenience, not capability.
• Log the generated URLs in development (debug log level) so you can spot a bad preset without opening dev tools on every page.