Download the PHP package superbig/craft3-imgix without Composer

Imgix plugin for Craft CMS 5.x

Use Imgix with Craft CMS to automatically optimize, resize, and transform your images on-the-fly.

What does this plugin do?

This plugin integrates Imgix's powerful image processing API with Craft CMS, giving you instant access to real-time image transformations. Instead of generating and storing multiple versions of your images on your server, Imgix handles all the heavy lifting in the cloud.

Key features:

• On-demand image transformations - Resize, crop, and optimize images dynamically via URL parameters
• Automatic format selection - Serve WebP, AVIF, or other modern formats automatically based on browser support
• Responsive images made easy - Generate perfect srcset attributes with minimal code
• Smart cropping - Automatically use Craft's focal points for intelligent cropping
• Lazy loading support - Built-in helpers for both JavaScript-based and native lazy loading
• Cache purging - Automatically purge Imgix's cache when you update assets in Craft
• Signed URLs - Secure your images with signed URLs to prevent unauthorized transformations

Perfect for high-traffic sites that need fast, optimized images without the server overhead.

Table of contents

• Requirements
• Installation
• Configuration
  • Quick start
  • Configuration options
  • Environment variables
• Usage
  • Basic usage
  • Transform options
  • Lazy loading
  • Advanced usage
• Common use cases
• Preventing upscaling
• Troubleshooting
• Roadmap

Understanding Volume Mapping:

The imgixDomains array maps your Craft volume handles to Imgix domains. The plugin looks up the asset's volume handle to determine which Imgix domain to use.

• Simple mapping: 'uploads' => 'my-site.imgix.net' - all assets from the 'uploads' volume use this domain
• Path mapping: 'heroImages' => 'my-site.imgix.net/heroes' - adds a path prefix to all images
• Multiple domains: You can use different Imgix domains for different volumes

Environment variables

It's recommended to store sensitive values like API keys in environment variables. In your .env file:

2. Then tell Composer to load the plugin:

3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Imgix.

Configuration

Quick start

Copy the config.php file from the plugin's src directory into your Craft project's config folder and rename it to imgix.php.

Basic configuration example:

Configuration options

Create a config/imgix.php file with the following options:

Understanding Volume Mapping:

The imgixDomains array maps your Craft volume handles to Imgix domains. The plugin looks up the asset's volume handle to determine which Imgix domain to use.

• Simple mapping: 'uploads' => 'my-site.imgix.net' - all assets from the 'uploads' volume use this domain
• Path mapping: 'heroImages' => 'my-site.imgix.net/heroes' - adds a path prefix to all images
• Multiple domains: You can use different Imgix domains for different volumes

Advanced Configuration (Array Format)

For more control over each domain, you can use the array format to specify domain-specific settings including secure tokens and path prefixes:

Array format options:

• domain (required): The Imgix domain (e.g., 'my-site.imgix.net')
• signingToken (optional): Secure URL token specific to this Imgix source. Each Imgix source has its own token.
• path (optional): Path prefix for all images from this volume (e.g., 'subfolder/path'). Leading and trailing slashes are automatically handled.

When to use array format:

• Multiple Imgix sources with different secure tokens: Each Imgix source generates its own secure token. Use the array format to specify a different signingToken for each volume.
• Per-domain path prefixes: If different volumes need different path prefixes on the same Imgix domain.
• Future extensibility: The array format allows for additional per-domain options in future updates.

Note: The imgixSignedToken configuration option is deprecated. Use signingToken within the imgixDomains array format instead. The legacy option is still supported for backward compatibility.

Environment variables

It's recommended to store sensitive values like API keys in environment variables. In your .env file:

Then reference them in config/imgix.php:

Basic Configuration (String Format)

Usage

Basic usage

The plugin provides the craft.imgix.transformImage() method in Twig templates to transform images using imgix.

Simple image transformation:

Multiple transforms (responsive images):

Transform options

Imgix supports a wide range of transformation parameters. Here are the most commonly used:

Size & Cropping:

Image Quality & Format:

Effects & Adjustments:

Default Options:

Apply default options to all transforms:

Focal Points:

The plugin automatically uses Craft's focal point if set on the asset:

Lazy loading

JavaScript-based lazy loading:

Native browser lazy loading:

Custom lazy load prefix:

In your config/imgix.php:

Advanced usage

Using with Element API:

Custom attributes on image tags:

Working with string URLs:

Debugging transforms:

Common use cases

Responsive hero image

Product thumbnail gallery

Blog post featured images

Art direction with different crops

Background image with blur effect

Optimized avatar images

Preventing Upscaling

By default, Imgix will upscale images to match the requested dimensions. For example, if your original image is 800×600 pixels but you request 1920×1080, Imgix will enlarge it. If you want to prevent images from being upscaled beyond their original size, you can enable the preventUpscaling setting in config/imgix.php:

When enabled, this setting automatically applies fit=max to all transformations that don't already have a fit parameter specified. The fit=max mode scales images to fit within the specified dimensions while preventing upscaling beyond the original image size.

If you need to override this behavior for specific transformations, you can explicitly set a different fit parameter:

Troubleshooting

Images not loading

Problem: Images aren't transforming or showing up.

Solutions:

1. Check that your volume handle matches the key in imgixDomains config
2. Verify your Imgix domain is correct in the config file
3. Ensure your Imgix source is properly configured to point to your asset storage
4. Check that the asset exists and has a valid path

Signed URLs not working

Problem: Getting 403 errors or signature mismatches.

Solutions:

1. For array format: Verify the signingToken in your volume's array configuration matches the token in your Imgix source settings
2. For legacy format: Verify your imgixSignedToken matches the token in your Imgix source settings
3. Make sure URL signing is enabled in your Imgix source
4. Check for trailing/leading whitespace in your token
5. Multiple sources: If using multiple Imgix sources, ensure each volume has the correct signingToken specified in the array format (each source has its own token)

Purging not working

Problem: Asset cache isn't being purged when assets are updated.

Solutions:

1. Verify you have a valid API key with purge permissions
2. Generate a new API key from https://dashboard.imgix.com/api-keys/new
3. Ensure the API key has "Purge" permission enabled
4. Check that you're not using an old API key (< 50 characters) - these are deprecated

Focal point not applied

Problem: Crop isn't respecting Craft's focal point.

Solutions:

1. Ensure you're using fit: 'crop' in your transform
2. Verify the focal point is set on the asset in Craft
3. Check that you're not manually overriding fp-x and fp-y in your transforms

Quality issues

Problem: Images look too compressed or low quality.

Solutions:

1. Adjust the q parameter (quality): q: 85 for higher quality
2. Use auto: 'format,compress' to let Imgix optimize automatically
3. Remove excessive sharpening: sharp: 5-10 is usually sufficient
4. Ensure source images are high quality

Lazy loading not working

Problem: Lazy loading attributes not appearing.

Solutions:

1. Verify you're passing lazyLoad: true in the options: {{ image.img({ lazyLoad: true }) }}
2. Check your lazyLoadPrefix setting in config
3. Ensure your JavaScript lazy loading library is properly initialized
4. For native loading, use loading: 'lazy' instead of lazyLoad: true

Different environments

Problem: Images work locally but not in production (or vice versa).

Solutions:

1. Use environment variables for your Imgix configuration
2. Ensure .env files are properly configured for each environment
3. Check that volume handles are consistent across environments
4. Verify Imgix sources are configured for both development and production URLs

Roadmap

• Look into improving srcset/API
• Look into built-in image editor integration
• Additional Imgix parameter helpers
• Improved focal point handling

Additional resources

• Imgix Documentation
• Imgix URL API Reference
• Craft CMS Asset Documentation

Brought to you by Superbig