Imgix Php Laravel Package

Getting Started

1. Install via Composer: composer require imgix/imgix-php
2. Initialize the client: Provide your imgix source domain (e.g., https://your-domain.imgix.net) and optionally your API signing key (required for secure URLs).

   use imgix\UrlBuilder;
   
   $builder = new UrlBuilder('https://your-domain.imgix.net', $apiKey = 'your-signing-key');
   

3. Generate a basic URL: Chain parameters fluently to build a URL:

   $url = $builder->createUrl('sample.jpg', [
       'w' => 800,
       'h' => 600,
       'fit' => 'crop',
   ]);
   // → https://your-domain.imgix.net/sample.jpg?w=800&h=600&fit=crop&s=...
   

   First use case: Replace static image URLs in Blade views with dynamic, responsive, signed imgix URLs.

Implementation Patterns

• Laravel Integration:
  • Bind UrlBuilder as a singleton in a service provider or helper function.
  • Create a global imgix_url() helper for view-level usage:

    function imgix_url(string $path, array $params = []): string {
        return app(UrlBuilder::class)->createUrl($path, $params);
    }
    

• Responsive Images: Use getSrcSet() to generate responsive srcset strings for <img> tags:

  $srcset = $builder->getSrcSet('mountain.jpg', ['w' => [200, 400, 800]]);
  // → '...200.jpg 200w, ...400.jpg 400w, ...800.jpg 800w'
  

• Format Optimization: Auto-detect format support via fm + auto:

  $url = $builder->createUrl('photo.jpg', [
      'fm' => 'auto',
      'q' => 70,
      'w' => 1024,
  ]);
  

• Centralize Defaults: Pre-configure common transforms (e.g., auto=format, q=75) in your UrlBuilder instance setup.

Gotchas and Tips

• Signing Key Security: Never hardcode the signing key—use environment variables (IMGIX_API_KEY) and load conditionally (e.g., only in production).
• Parameter Overriding: createUrl() merges params safely but does not deduplicate conflicting keys—ensure your code doesn’t accidentally pass duplicate keys (e.g., w twice).
• Empty Parameter Handling: imgix ignores empty/invalid params silently; verify outputs in browser DevTools if transforms aren’t applied.
• Encoding Edge Cases: Params with special characters (e.g., text or watermark) are auto-encoded, but for complex use cases (e.g., JSON in txt), manually rawurlencode() if needed.
• Testing: Mock UrlBuilder in unit tests—don’t hit real endpoints.
• Caching: imgix URLs are CDN-cached; changing any parameter invalidates the cache. Plan parameter sets carefully for cache efficiency.