Statamic Responsive Images Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require spatie/statamic-responsive-images
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Spatie\ResponsiveImages\ServiceProvider" --tag="config"
   

2. Fieldtype Integration

   • Add the fieldtype to your Statamic blueprint:

     fields:
       responsive_image:
         type: spatie/responsive_images
         display: "Responsive Image"
     

   • Configure the fieldtype in config/responsive-images.php (e.g., set default breakpoints).

3. First Use Case

   • Insert the field into a collection entry.
   • Use the field in a template:

     {{ entry.responsive_image|responsive_image }}
     

   • Outputs an <picture> element with optimized srcset and sizes attributes.

Implementation Patterns

Core Workflows

1. Art Direction

   • Define breakpoints in config/responsive-images.php:

     'breakpoints' => [
         'sm' => 640,
         'md' => 1024,
         'lg' => 1440,
     ],
     

   • Use the fieldtype’s "Art Direction" tab to assign specific images per breakpoint.

2. Dynamic Image Generation

   • Leverage the responsive_image Twig filter:

     {{ entry.hero_image|responsive_image({
         'breakpoints': ['sm', 'md', 'lg'],
         'sizes': '(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw',
         'fallback': entry.hero_image.default
     }) }}
     

3. Integration with Statamic Assets

   • Store images in Statamic’s assets container.
   • Reference them in the fieldtype via the media picker.

4. Caching and Performance

   • Enable disk caching in config:

     'cache' => [
         'enabled' => true,
         'driver' => 'file', // or 'redis'
     ],
     

   • Regenerate thumbnails via:

     php artisan responsive-images:regenerate
     

5. Custom Directives

   • Extend the fieldtype with custom directives (e.g., for lazy loading):

     {{ entry.responsive_image|responsive_image({
         'directives': ['loading="lazy"']
     }) }}
     

Gotchas and Tips

Pitfalls

1. Breakpoint Mismatch

   • Ensure sizes attribute in Twig matches the breakpoints in config. Mismatches cause unnecessary image loads.
   • Example: If using breakpoints: ['sm', 'md'], omit lg from sizes unless needed.

2. Asset Container Paths

   • Hardcoding container paths (e.g., assets/images) in config breaks if containers are renamed. Use Statamic’s asset() helper or dynamic paths:

     'asset_container' => 'assets/images',
     

3. Cache Invalidation

   • Clearing Statamic’s cache (php artisan statamic:clear) doesn’t reset responsive image cache. Use:

     php artisan responsive-images:clear-cache
     

4. Fieldtype Configuration Overrides

   • Blueprint-level overrides (e.g., breakpoints) take precedence over global config. Test thoroughly.

Debugging

• Log Breakpoints Add this to AppServiceProvider to debug generated breakpoints:

  Spatie\ResponsiveImages\ResponsiveImage::macro('debug', function () {
      return [
          'breakpoints' => $this->breakpoints,
          'sizes' => $this->sizes,
          'srcset' => $this->srcset,
      ];
  });
  

  Usage:

  {{ entry.responsive_image|responsive_image|debug }}
  

• Check Disk Permissions If images fail to generate, verify storage/app/responsive-images is writable:

  chmod -R 755 storage/app/responsive-images
  

Extension Points

1. Custom Image Processing

   • Extend the Spatie\ResponsiveImages\Image class to add filters (e.g., blur effects):

     namespace App\Extensions;
     use Spatie\ResponsiveImages\Image;
     
     class CustomImage extends Image {
         public function blur($amount) {
             return $this->applyFilter('blur', $amount);
         }
     }
     

   • Bind the extension in AppServiceProvider:

     Spatie\ResponsiveImages\ResponsiveImage::macro('custom', function () {
         return new CustomImage($this->asset);
     });
     

2. WebP Fallback

   • Add a WebP fallback to the responsive_image filter:

     {{ entry.responsive_image|responsive_image({
         'formats': ['webp', 'jpg'],
         'fallback_format': 'jpg'
     }) }}
     

3. Statamic Entry Events

   • Regenerate responsive images on entry update:

     use Spatie\ResponsiveImages\Facades\ResponsiveImage;
     
     Event::listen(EntryUpdated::class, function ($event) {
         if ($event->entry->has('responsive_image_field')) {
             ResponsiveImage::regenerate($event->entry->responsive_image_field->value);
         }
     });
     

4. Custom Storage

   • Override the storage path for responsive images:

     'storage' => [
         'path' => 'custom/path/responsive-images',
         'disk' => 's3', // Use AWS S3, etc.
     ],