Download the PHP package maccesar/laravel-glide-enhanced without Composer

Laravel Glide Enhanced

A Laravel package for dynamic image processing based on Spatie/Laravel-Glide.

Important Update (v3.x)

Version 3 supports Laravel 12–13 and PHP 8.2+. Image files are now isolated under the configured images.source_root (images by default), and public processing is rate-limited and strictly validated. See UPGRADE.md.

Previous Update (v2.x)

The default route prefix has changed from /img/ to /glide/ to avoid conflicts with other packages, especially laravel-dropzone-enhanced.

Before: https://your-site.com/img/path/image.jpg
Now: https://your-site.com/glide/path/image.jpg

See the UPGRADE.md file for migration instructions.

Features

• Dynamic image processing (resizing, cropping, format conversion)
• Image optimization for web use
• Automatic caching for improved performance
• Configurable default images by category
• Predefined presets for consistent image usage
• HasImages trait for Eloquent models
• ImageProcessor facade for easy access
• Configurable routes to avoid conflicts with other packages
• Full compatibility with Laravel Dropzone Enhanced

Current Limitations

• The package currently works only with local files (using the 'local' and 'public' disks)
• External storage services like AWS S3 are not fully supported for image processing
• URLs from external services are recognized but cannot be dynamically processed

Installation

You can install the package via composer:

The package will automatically register its service provider and facade.

Then publish the configuration file:

Requirements

• PHP 8.2 or higher (Laravel 13 requires PHP 8.3+)
• Laravel 12.x or 13.x
• Spatie's Laravel Glide package

Configuration

The config/images.php file contains several configuration options:

Disk Configuration

The disk configuration selects a local Laravel filesystem. Sources are never read from its general root: with the defaults, photo.jpg resolves to storage/app/public/images/photo.jpg. Put watermarks in storage/app/public/watermarks. Remote disks such as S3 are not supported by the local image processor.

To retain another dedicated layout, configure its safe root explicitly:

Make sure the disk you specify is properly configured in your config/filesystems.php file.

Route Configuration

The routes section allows you to customize how the package registers its routes:

If you need to avoid conflicts with other packages, you can change the route prefix or disable the routes entirely and implement your own.

Basic Usage

Facades Available

The package provides two facades for your convenience:

Both facades provide identical functionality. We recommend using Img for cleaner, more readable code.

Image Processing URLs

HasImages Trait for Eloquent Models

HasImages Trait Reference

The HasImages trait provides comprehensive image processing methods for Eloquent models. Add this trait to any model that needs dynamic image processing capabilities.

Setup

Available Methods

Method Details

getImageUrl($type = 'default', $dimensions = null, $format = 'pjpg', $watermark = null, $extraParams = [])

Generate a custom image URL with specific parameters.

Parameters:

• $type (string): Image type identifier (default, main, thumbnail, etc.)
• $dimensions (string|null): Format: '300' or '300x200' (width x height)
• $format (string): Output format (jpg, png, webp, pjpg)
• $watermark (string|null): Watermark to apply
• $extraParams (array): Additional parameters for Glide

Example:

getImageWebpUrl($type = 'default', array $params = [])

Generate a WebP optimized image URL using the ImageProcessor facade.

Parameters:

• $type (string): Image type identifier (default, main, thumbnail, etc.)
• $params (array): Glide parameters for image processing

Example:

getImagePreset($type = 'default', $preset = 'thumbnail')

Generate image URL using a predefined preset configuration.

Parameters:

• $type (string): Image type identifier (default, main, thumbnail, etc.)
• $preset (string): Preset name (thumbnail, medium, large, social)

Example:

Image Path Resolution

The trait automatically resolves image paths using these strategies:

1. Custom methods: get{Type}ImagePath() method in your model
2. Model properties: Direct property access ($this->{$type})
3. Backward compatibility: For 'default' type, checks image, imagen, or foto properties

Example:

Image Presets

Laravel Glide Enhanced includes predefined presets for common image sizes and formats. These presets ensure consistent image processing across your application.

Available Presets

Preset Configuration

The presets are defined in your config/images.php file:

Custom Presets

You can create your own presets by adding them to the configuration:

Using Custom Presets

Preset Best Practices

1. thumbnail: Perfect for user avatars, small product images in lists
2. medium: Ideal for product cards, blog post featured images
3. large: Best for hero images, detailed product views
4. social: Optimized for social media sharing (Facebook, Twitter, LinkedIn)

Performance Tips:

• Use WebP format for modern browsers (better compression)
• Use JPG for social media sharing (better compatibility)
• Crop fit mode for consistent dimensions, max fit mode to preserve aspect ratio

Responsive Images with srcset

The package provides a convenient way to generate srcset attributes for responsive images with different pixel densities:

Quick Reference

Common Use Cases

Most Used Glide Parameters

Fit Mode Reference

• crop: Crops image to exact dimensions (may cut off parts)
• max: Resizes to fit within dimensions (preserves aspect ratio)
• fill: Fills dimensions exactly (may stretch image)
• stretch: Stretches to exact dimensions (ignores aspect ratio)

Applying Watermarks

You can apply watermarks to your images using the following parameters:

Important note: The watermark image must exist at the specified path within storage/app/public/. For example, if you use 'mark' => 'watermarks/logo.png', the file should be located at storage/app/public/watermarks/logo.png.

Usage in Blade Templates

Basic Image Display

Responsive Images

Product Gallery

Blog Post with Social Meta

E-commerce Product Card

Cache Cleaning

To clean the image cache, use the command:

To clean only images older than a specific number of days:

Components Registered

This package registers the following components in Laravel:

• Routes: A route with the prefix /glide/ (configurable via the routes.prefix config)
• Services: A singleton image-processor in the container
• Facade: ImageProcessor for easy access to the service
• Command: images:clean-cache for cache maintenance

Troubleshooting

Common Issues

Images Not Processing

Problem: Images return original size instead of processed versions.

Solutions:

1. Check that the images.php config file is published:

2. Verify the disk configuration in config/images.php:

3. Ensure images exist in the specified storage disk:

4. Clear image cache:

Route Not Found Errors

Problem: URLs like /glide/storage/image.jpg return 404.

Solutions:

1. Check that routes are enabled in config:

2. Clear route cache:

3. Verify routes are registered:

WebP Images Not Working

Problem: WebP images not displaying in some browsers.

Solutions:

1. Provide fallback using <picture> element:

2. Check server WebP support by testing a direct URL

Performance Issues

Problem: Slow image loading or processing.

Solutions:

1. Implement image preloading for critical images:

2. Use appropriate image formats:

   • WebP for modern browsers (smaller files)
   • JPG for photos with many colors
   • PNG for images with transparency

3. Optimize cache settings in config/images.php:

4. Use CDN for static assets in production

FAQ

Q: Can I use this with external storage like S3? A: Currently, the package works only with local storage disks (local and public). External storage support is planned for future versions.

Q: How do I create custom presets? A: Add them to your config/images.php file under the presets array. See the "Custom Presets" section above.

Q: Can I change the route prefix? A: Yes, modify the routes.prefix value in your config file. Remember to clear caches after changes.

Q: How do I disable the package routes? A: Set routes.enabled to false in your config file if you want to implement custom routing.

Q: What's the difference between getImageUrl() and getImageWebpUrl()? A: getImageWebpUrl() uses the ImageProcessor facade and accepts an array of parameters. getImageUrl() gives you full control over individual parameters including dimensions, format, and watermarks.

License

MIT

Credits

Developed by César Estrada (macCesar)