Laravel Imgix Laravel Package

Getting Started

Install and wire it up:

composer require nasyrov/laravel-imgix

On Laravel 5.5+ auto-discovery should register Nasyrov\Laravel\Imgix\ImgixServiceProvider and the Imgix facade. On newer Laravel versions (9/10/11) verify this still happens — if not, add them to config/app.php:

'providers' => [
    Nasyrov\Laravel\Imgix\ImgixServiceProvider::class,
],
'aliases' => [
    'Imgix' => Nasyrov\Laravel\Imgix\Facades\Imgix::class,
],

Publish the config (tag name may be imgix or omitted):

php artisan vendor:publish --provider="Nasyrov\Laravel\Imgix\ImgixServiceProvider"

This drops config/imgix.php into your app. The two things you care about are the source (your imgix subdomain, e.g. my-source.imgix.net or a custom CNAME) and, if you use signed URLs, the signing key.

Configure via .env rather than editing the config directly. Add keys like:

IMGIX_SOURCE=my-source.imgix.net
IMGIX_SECURE=true
IMGIX_SIGN_KEY=

(Confirm the exact env var names the package reads — open config/imgix.php after publishing. Older versions of small packages sometimes hardcode the env key.)

First use case — generate a resized, cropped hero image:

use Nasyrov\Laravel\Imgix\Facades\Imgix;

$url = Imgix::create('photos/hero.jpg', [
    'w'   => 1200,
    'h'   => 630,
    'fit' => 'crop',
]);

// https://my-source.imgix.net/photos/hero.jpg?w=1200&h=630&fit=crop

Where to look first: the published config/imgix.php and the facade class (vendor/nasyrov/laravel-imgix/src/). Small packages like this one have a thin API surface, so reading the facade + service class end-to-end takes five minutes and removes all guesswork about method names and parameter merging.

Implementation Patterns

Store paths, resolve URLs at render time. Never persist fully-qualified imgix URLs in the database. Persist something like uploads/products/123/main.jpg and build the URL in the view/controller. That way if you change source domains, add signing, or restructure folders, you don't need a data migration.

// migration / model
$table->string('image_path')->nullable();

// accessor
public function getImageUrlAttribute(): ?string
{
    return $this->image_path
        ? Imgix::create($this->image_path, ['w' => 800, 'fit' => 'max'])
        : null;
}

Wrap it in a Blade component so views stay readable and your transformation presets are centralized:

{{-- resources/views/components/imgix.blade.php --}}
@props(['path', 'params' => []])

<img
    src="{{ \Nasyrov\Laravel\Imgix\Facades\Imgix::create($path, $params + ['auto' => 'format,compress']) }}"
    {{ $attributes }}
>

<x-imgix path="photos/hero.jpg" :params="['w' => 1600, 'fit' => 'crop']" class="w-full" />

Responsive srcset. Imgix shines when you feed it multiple widths. Build a small helper that maps a breakpoint array to srcset descriptors:

function imgix_srcset(string $path, array $widths = [400, 800, 1200, 1600]): string
{
    return collect($widths)
        ->map(fn ($w) => Imgix::create($path, ['w' => $w, 'fit' => 'max', 'auto' => 'format']) . " {$w}w")
        ->implode(', ');
}

<img
    src="{{ Imgix::create($path, ['w' => 800, 'auto' => 'format']) }}"
    srcset="{{ imgix_srcset($path) }}"
    sizes="(max-width: 768px) 100vw, 50vw"
    alt="..."
>

Preset/config layering. Keep a base set of parameters (e.g. auto=format,compress) and merge per-call params over it. This is the single biggest maintenance win — you only change compression behavior in one place:

$base = config('imgix.defaults', ['auto' => 'format,compress']);
$url  = Imgix::create($path, array_merge($base, $overrides));

Signed URLs for private sources. If your source is restricted, URLs need an s= signature. Confirm whether the package accepts a signing key in config and generates the signature — if it only builds the query string, you sign in your own wrapper. Keep the signing key server-side only; never render signed URLs from a key exposed to JS.

Testing. Bind a fake into the container or use the facade's shouldReceive. Because the package is thin, the cheapest reliable approach is to assert against the URL string produced:

Imgix::shouldReceive('create')
    ->once()
    ->with('photos/hero.jpg', ['w' => 800])
    ->andReturn('https://test.imgix.net/photos/hero.jpg?w=800');

Config per environment. Local/dev should point at either the real imgix source (safe — it's a CDN) or a placeholder. Never hardcode the source in code; always read from config('imgix.*') so staging and production can diverge.

Gotchas and Tips

• Package age is the #1 risk. Last release was June 2020. It predates Laravel 8's model changes and certainly Laravel 10/11. Check composer.json constraints before installing on a modern app; you may need --with-all-dependencies or a fork/composer require with a widened constraint. If auto-discovery fails, register the provider manually (see above).

• Leading slashes and path normalization. Imgix expects a path without a leading slash (photos/hero.jpg, not /photos/hero.jpg). Double-check how the package joins source + path; a stray / produces //photos/hero.jpg and a 404. Normalize inputs with ltrim($path, '/') in your own wrapper.

• URL-encode paths. Spaces, #, ?, and non-ASCII characters in filenames will break signed URLs and occasionally unsigned ones. Run paths through rawurlencode-per-segment (not the whole path, or you'll encode the slashes) in your wrapper if you allow arbitrary upload names.

• Parameter order and CDN caching. Imgix caches on the exact URL string. w=800&h=600 and h=600&w=800 are different cache keys. If you build params from arrays merged in different orders across call sites, you'll fragment your CDN cache. ksort() the params before generating the URL to keep keys canonical.

• Only pass real imgix params. Unknown query parameters are often ignored by imgix (or worse, silently change behavior). Use the imgix rendering API short names (w, h, fit, crop, fm, q, auto, dpr, blur, txt). Typos like width= won't error — they'll just be ignored, making "why isn't my image resizing?" a silent bug.

• auto=format is not a substitute for srcset. auto=format picks WebP/AVIF based on Accept, but you still need width variants to serve appropriate sizes. Combine both.

• Signing key secrecy. If the package supports signing, the key must come from config/.env and never be interpolated into frontend JS or logged. Signed URLs are time/param-sensitive; if the package doesn't expose an expiry, add it in your own layer.

• Debugging a wrong URL. Dump the raw string (dump((string) $url)) rather than inspecting an object — the facade may return a Stringable or a plain string depending on version. To inspect what imgix actually did, append &fm=json and fetch the URL; imgix returns processing metadata.

• Extension points are minimal — plan to wrap it. Given the package's size and age, treat it as a small URL builder and wrap it in your own ImageService/helper. That gives you a single place to add signing, canonical param ordering, defaults, path normalization, and a future swap to the official imgix/imgix-php SDK or plain string building if the package is abandoned.

• Don't over-engineer transformations in PHP. Imgix does the work; your PHP should only assemble strings. Resist building resize/crop logic locally — push it into query parameters so the CDN does it at the edge.