PHPackages askancy/laravel-smart-thumbnails - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Image & Media](/categories/media) 4. / 5. askancy/laravel-smart-thumbnails ActiveLibrary[Image & Media](/categories/media) askancy/laravel-smart-thumbnails ================================ Advanced thumbnail generation with smart cropping for Laravel applications 2.0(8mo ago)121MITPHPPHP ^8.1CI failing Since Jun 28Pushed 8mo agoCompare [ Source](https://github.com/Askancy/laravel-smart-thumbnails)[ Packagist](https://packagist.org/packages/askancy/laravel-smart-thumbnails)[ RSS](/packages/askancy-laravel-smart-thumbnails/feed)WikiDiscussions main Synced 1w ago READMEChangelog (7)Dependencies (6)Versions (7)Used By (0) Laravel Smart Thumbnails ======================== [](#laravel-smart-thumbnails) [![Laravel Smart Thumbnails Demo](https://private-user-images.githubusercontent.com/789702/460313328-3c71d5d7-19ca-4703-9612-d3eeaed23183.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODMzODI1ODEsIm5iZiI6MTc4MzM4MjI4MSwicGF0aCI6Ii83ODk3MDIvNDYwMzEzMzI4LTNjNzFkNWQ3LTE5Y2EtNDcwMy05NjEyLWQzZWVhZWQyMzE4My5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwNzA2JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDcwNlQyMzU4MDFaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT0xMzE4NDUzM2RhYjUyOTJkYTM0NTI1M2YzYzkzZTllMWM4MTAyNGYxMmVmNTRiODgxZjNiNzRiY2FjYzE4MDYwJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZyZXNwb25zZS1jb250ZW50LXR5cGU9aW1hZ2UlMkZwbmcifQ.znq3eHNZbZj2vIWEL8a1qsdAkVh4aazprULdH120R6M)](https://private-user-images.githubusercontent.com/789702/460313328-3c71d5d7-19ca-4703-9612-d3eeaed23183.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODMzODI1ODEsIm5iZiI6MTc4MzM4MjI4MSwicGF0aCI6Ii83ODk3MDIvNDYwMzEzMzI4LTNjNzFkNWQ3LTE5Y2EtNDcwMy05NjEyLWQzZWVhZWQyMzE4My5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwNzA2JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDcwNlQyMzU4MDFaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT0xMzE4NDUzM2RhYjUyOTJkYTM0NTI1M2YzYzkzZTllMWM4MTAyNGYxMmVmNTRiODgxZjNiNzRiY2FjYzE4MDYwJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZyZXNwb25zZS1jb250ZW50LXR5cGU9aW1hZ2UlMkZwbmcifQ.znq3eHNZbZj2vIWEL8a1qsdAkVh4aazprULdH120R6M) **The ultimate thumbnail generation package for Laravel.** Featuring intelligent smart-cropping, multi-disk support, automatic subdirectory organization, and bulletproof error handling that ensures your application's UI never breaks. [![Latest Version on Packagist](https://camo.githubusercontent.com/466914cd7d3648bc4845309cdef0804d66d0d3eb2aa7333f83ed199a4aebd3ca/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f61736b616e63792f6c61726176656c2d736d6172742d7468756d626e61696c732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/askancy/laravel-smart-thumbnails)[![Total Downloads](https://camo.githubusercontent.com/01ec24e4eb973181b7286be190e65263024b7921ba15d20c3ea1efee8622e609/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f61736b616e63792f6c61726176656c2d736d6172742d7468756d626e61696c732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/askancy/laravel-smart-thumbnails)[![Tests](https://camo.githubusercontent.com/410a12c1ba6a8793fc02ccec4b3c655ad70ed4903840fe2910ba8498ca452fa6/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f61736b616e63792f6c61726176656c2d736d6172742d7468756d626e61696c732f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/askancy/laravel-smart-thumbnails/actions)[![License: MIT](https://camo.githubusercontent.com/a7e65aee57b11d28e4caff8b945729a66be0bb663f7f93bd24c5aa65699f148e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e7376673f7374796c653d666c61742d737175617265)](https://opensource.org/licenses/MIT) --- ✨ Features ---------- [](#-features) - 🧠 **Intelligent Smart Crop Algorithm** - Energy-based detection ensures the most important parts of your images are never cropped out. - 🛡️ **Bulletproof Error Handling** - Fails gracefully with automatic fallbacks (original image, placeholders, or generated SVGs) to guarantee your layout remains intact. - 🖼️ **Modern Format Support** - Seamlessly generates modern image formats, including WebP and AVIF, for maximum compression and performance. - 📁 **Massive Scale Subdirectories** - Handles millions of thumbnails efficiently via customizable subdirectory distribution strategies (e.g., hash prefixes, dates). - 💾 **Multi-Disk Architecture** - Fully supports local, S3, scoped disks, and any custom Laravel filesystem. - 🎨 **Responsive Variants** - Easily define multiple responsive presets (e.g., thumb, card, hero, zoom) within your configuration. - ⚡ **High Performance & Cache** - Utilizes Smart Cache Tagging for targeted invalidation without flushing your entire application cache. - 🎯 **Intervention Image 3.x Ready** - Full compatibility with the latest image manipulation APIs. --- 📋 Requirements -------------- [](#-requirements) - **PHP** 8.1 or higher - **Laravel** 10.0, 11.0, or 12.0 - **Intervention Image** 3.9+ - **GD** or **ImageMagick** PHP Extension (ImageMagick is required for AVIF support) - *Optional:* Redis or Memcached (for cache tagging capabilities) --- 📦 Installation -------------- [](#-installation) Install the package via Composer: ``` composer require askancy/laravel-smart-thumbnails ``` Publish the configuration file: ``` php artisan vendor:publish --tag=laravel-smart-thumbnails-config ``` --- 🚀 Quick Start ------------- [](#-quick-start) Laravel Smart Thumbnails is designed to be effortless. Use the facade directly in your Blade views: ### The Bulletproof "Silent" Mode (Recommended) [](#the-bulletproof-silent-mode-recommended) This mode **never** throws exceptions. If an image is missing or the disk fails, it silently falls back to a placeholder. ``` {{-- Implicit silent mode using urlSafe() --}} {{-- Explicit silent mode chaining --}} ``` ### The "Strict" Mode (For Debugging / Admin Panels) [](#the-strict-mode-for-debugging--admin-panels) If you want exceptions to be thrown when something goes wrong (e.g., missing original file), use strict mode: ``` {{-- May throw an exception if the image is missing --}} ``` ### Advanced Responsive Pictures [](#advanced-responsive-pictures) Leverage configured variants to easily render `` tags for responsive designs: ``` ``` --- ⚙️ Configuration ---------------- [](#️-configuration) Your `config/thumbnails.php` file is where the magic happens. You can define multiple "presets", each representing a distinct context (like `products`, `avatars`, `gallery`). ``` 'presets' => [ 'products' => [ 'format' => 'webp', // Target format (webp, avif, jpg, png) 'smartcrop' => '400x400', // Dimensions for the main thumbnail 'destination' => [ 'disk' => 'public', // Target storage disk 'path' => 'thumbnails/products/' // Target path ], 'quality' => 85, 'smart_crop_enabled' => true, // Use the intelligent cropping algorithm 'subdirectory_strategy' => 'hash_prefix', // Distribute files to prevent folder limits // Define responsive variants sharing the same preset logic 'variants' => [ 'thumb' => ['smartcrop' => '120x120', 'quality' => 75], 'card' => ['smartcrop' => '250x250', 'quality' => 85], 'detail' => ['smartcrop' => '600x600', 'quality' => 95], 'zoom' => ['smartcrop' => '1200x1200', 'quality' => 95], ] ], ], ``` ### AVIF Format Support [](#avif-format-support) For ultra-modern web performance, AVIF provides ~50% smaller file sizes than JPEG and ~30% smaller than WebP. To use AVIF, ensure you have the **ImageMagick** extension installed and update your driver in `config/thumbnails.php`: ``` 'intervention_driver' => 'imagick', // Must be 'imagick', GD does not support AVIF yet ``` Then, simply set `'format' => 'avif'` in your presets! --- 📁 Subdirectory Optimization --------------------------- [](#-subdirectory-optimization) When you have millions of images, storing them all in a single folder slows down the filesystem drastically. Smart Thumbnails solves this automatically using customizable strategies: - `'hash_prefix'` *(Recommended)*: Uses the first two characters of the MD5 hash (e.g. `a/b/image.jpg`). Perfectly distributes files. - `'date_based'`: Organizes by generation date (e.g. `2025/12/31/image.jpg`). - `'filename_prefix'`: Groups by the starting letters of the filename. - `'hash_levels'`: Deeper, multi-level nesting for massive scale (e.g. `a/b/c/image.jpg`). --- 🛠️ Maintenance & CLI Commands --------------------------------- [](#️-maintenance--cli-commands) Keep your application fast and clean using the built-in Artisan commands: ``` # Purge all generated thumbnails across all disks php artisan thumbnail:purge # Purge thumbnails only for a specific preset php artisan thumbnail:purge products --confirm ``` You can also analyze your usage via Tinker: ``` php artisan tinker >>> Thumbnail::getSystemStats(); >>> Thumbnail::analyzeDistribution('products'); ``` --- 🔄 Upgrade Guide (v2.0) ---------------------- [](#-upgrade-guide-v20) If you are upgrading from an older version, the transition is **100% backwards compatible**. No code changes are required in your views or controllers. **Enhancements included automatically:** - Upgrade to Intervention Image 3.x. - Better memory management and Cache Tagging (Memcached/Redis recommended). - Advanced Smart Cropping algorithm optimizations. Make sure to clear your caches after upgrading: ``` php artisan cache:clear php artisan config:clear ``` --- 🤝 Contributing -------------- [](#-contributing) We welcome pull requests and issues! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and development process. Looking to help with our AI/Smart Crop Roadmap? Check out [SMART\_CROP\_ROADMAP.md](SMART_CROP_ROADMAP.md). --- 📄 License --------- [](#-license) The MIT License (MIT). Please see [LICENSE.md](LICENSE) for more information. 🙏 Credits --------- [](#-credits) - Created and maintained by [Askancy](https://github.com/askancy) - Image manipulation powered by [Intervention Image](https://github.com/Intervention/image) - Smart crop algorithm inspired by [dont-crop](https://github.com/jwagner/dont-crop/) --- > 💡 **Pro Tip**: Always use `->urlSafe()` when rendering images in public user-facing views to guarantee your frontend never breaks due to a missing file! ### Health Score 34 — LowBetter than 74% of packages Maintenance61 Regular maintenance activity Popularity8 Limited adoption so far Community6 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~33 days Recently: every ~41 days Total 6 Last Release 248d ago Major Versions 1.8 → 2.02025-12-11 ### Community Maintainers ![](https://www.gravatar.com/avatar/0774a513bb5b13d7d314c88cbce01726eddb0e4282a0899116ab3ece887ceda6?d=identicon)[Askancy](/maintainers/Askancy) --- Top Contributors [![Askancy](https://avatars.githubusercontent.com/u/789702?v=4)](https://github.com/Askancy "Askancy (12 commits)") --- Tags laravelimageresizeThumbnailscropinterventionWebpavifsmart-crop ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/askancy-laravel-smart-thumbnails/health.svg) ``` [![Health](https://phpackages.com/badges/askancy-laravel-smart-thumbnails/health.svg)](https://phpackages.com/packages/askancy-laravel-smart-thumbnails) ``` ### Alternatives [unopim/unopim UnoPim Laravel PIM 10.8k2.5k](/packages/unopim-unopim)[intervention/image-laravel Laravel Integration of Intervention Image 1589.8M226](/packages/intervention-image-laravel)[mostafaznv/larupload Larupload is a ORM based file uploader for laravel to upload image, video, audio and other known files. 75487.1k6](/packages/mostafaznv-larupload)[code16/sharp Laravel Content Management Framework 79466.1k10](/packages/code16-sharp)[bkwld/croppa Image thumbnail creation through specially formatted URLs for Laravel 506520.9k31](/packages/bkwld-croppa)[reliqarts/laravel-guided-image Simplified and ready image manipulation for Laravel via intervention image. 341.7k](/packages/reliqarts-laravel-guided-image) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)