Download the PHP package moonlight-poland/laravel-context-aware-thumbnails without Composer

🖼️ Laravel Context-Aware Thumbnails™

Intelligent On-Demand Image Thumbnails with Smart Crop & Modern Formats

Copyright © 2024-2026 Moonlight Poland. All rights reserved.
Contact: [email protected]
License: Commercial License - Free for personal use, paid for commercial use
Repository: https://github.com/Moonlight4000/laravel-thumbnails

Generate image thumbnails on-the-fly in Laravel with Context-Aware Thumbnails™ - the only package that organizes thumbnails exactly where your content lives!

No pre-generation needed. No Redis required. Smart organization included.™

🌟 What Makes Us Unique?

1. 🎯 Context-Aware Organization™ - Thumbnails organized by user/post/album (no other package does this!)
2. ⚛️ React/Vue/JavaScript Support - The ONLY Laravel thumbnail package with sync-js command for frontend frameworks
3. 🔐 Signed URLs (Facebook-style) - Time-limited, cryptographically signed URLs to prevent hotlinking
4. 🤖 Smart Crop with AI Energy Detection - Automatically focuses on important image areas
5. 🚀 AVIF/WebP Support - Modern formats for 50%+ smaller file sizes
6. 🔒 Commercial Licensing - Professional support & tamper detection included

📋 Table of Contents

• Why Choose This Over Other Packages?
• What Makes Context-Aware Thumbnails™ Special?
• License Notice
• Features
• Installation
• Quick Start
• Configuration
• Usage
  • Blade Directive
  • Helper Function
  • Eloquent Trait
  • React / Vue / JavaScript Usage
  • Signed URLs (Facebook-style Protection)
• Context-Aware Thumbnails™
• Advanced Features
• Artisan Commands
• Testing
• Contributing
• License
• Credits

🏆 Why Choose This Over Other Packages?

📊 Complete Feature Comparison

🎯 Which Package Should You Choose?

Choose Laravel Context-Aware Thumbnails™ (moonlight-poland) if you need:

• ✅ Context-Aware organization (unique feature!)
• ✅ Thumbnails organized by user/post/album automatically
• ✅ React/Vue/JavaScript support (ONLY package with sync-js!)
• ✅ Signed URLs (Facebook-style) - Time-limited, cryptographically signed protection
• ✅ Auto-strategy: Context-Aware for models, Hash for paths
• ✅ Smart Crop with energy detection (v2.0)
• ✅ AVIF/WebP modern formats (v2.0)
• ✅ Variants system for multiple sizes (v2.0)
• ✅ Daily usage statistics sent to Moonlight (v2.0)
• ✅ Blade directives and helpers for easy use
• ✅ Automatic middleware fallback
• ✅ Commercial support with licensing
• ✅ Simple filesystem-based solution

🔥 What Makes Context-Aware Thumbnails™ Special?

Other packages dump all thumbnails in one folder. We organize them exactly where your content lives:

Benefits:

• ✅ Delete post → thumbnails automatically deleted with folder
• ✅ Per-user backups → backup specific user folders
• ✅ CDN routing → route different contexts to different CDNs
• ✅ Filesystem performance → fewer files per directory = faster I/O
• ✅ Security → isolate user content with directory permissions
• ✅ Organization → find thumbnails instantly, no database queries

⚠️ License Notice

This is a COMMERCIAL package with a dual-licensing model:

• 🆓 FREE for personal/non-commercial use
• 💼 PAID for commercial use ($500-$15,000/year)

See LICENSE.md for details.

Contact: [email protected]
GitHub: https://github.com/Moonlight4000/laravel-thumbnails

✨ Features

• 🔥 Context-Aware Thumbnails™ - Organize thumbnails by user/post/album/any structure (UNIQUE!)
• 🚀 On-Demand Generation - Thumbnails generated only when requested (lazy loading)
• 🔐 Signed URLs (Facebook-style) - Time-limited, cryptographically signed URLs to prevent hotlinking
• 💾 Filesystem Cache - Fast subsequent loads, no Redis/Memcached needed
• 🔌 Zero Configuration - Sensible defaults, works out of the box
• 🎨 Multiple Drivers - GD (default), Imagick, or Intervention Image
• 📐 3 Resize Methods - Resize (proportional), Crop (exact size), Fit (with padding)
• 🔧 Fully Configurable - Custom sizes, quality, drivers, paths, and more
• 🎯 Blade Directive - @thumbnail('path/image.jpg', 'small', 'post', ['user_id' => 1])
• ⚛️ React/Vue/JavaScript Helper - Full feature parity with PHP (sync-js command)
• 📦 Facade & Helpers - Multiple ways to use
• 🗑️ Auto Cleanup - Delete folder = thumbnails gone
• 🛠️ Artisan Commands - Generate or clear thumbnails via CLI
• ✅ Laravel 10, 11 & 12 - Tested on PHP 8.1–8.4

📦 Installation

Optional Dependencies (Recommended)

For best performance and advanced features, install these optional packages:

What you get with optional dependencies:

• ✅ Smart Crop - AI-powered energy detection (requires Intervention Image)
• ✅ AVIF format - Modern image format with 50% smaller files (requires ext-imagick)
• ✅ Better performance - Intervention Image is faster than GD for large images
• ⚠️ Without them - Package falls back to GD (works, but limited features)

License

Put your licence key in .env:

Local development on localhost / 127.0.0.1 / ::1 needs no key — in the local and testing environments only.

How the check behaves (3.2.0+):

• A verified licence is remembered for 30 days. In between there is no network traffic at all, across processes, queue workers and restarts.
• One attempt at a time, with a 2-second timeout. If the licence server cannot be reached, thumbnails keep working on the last verified licence and the check is retried after 24 hours.
• Only a definitive rejection from the licence server replaces thumbnails with a small "licence required" placeholder.

Verify now — and schedule it daily, so the check never runs during a page request:

Contact for licensing: [email protected]

Optional: Publish Config

Make Sure Storage is Linked

For React/Vue Apps: Generate JS Helper

REQUIRED if using React, Vue, or any JavaScript framework:

This generates resources/js/utils/thumbnails.js with your config contexts.

When to run:

• ✅ After installation
• ✅ After changing config/thumbnails.php
• ✅ After adding new contexts

See React/Vue Usage section below for details.

🚀 Quick Start

Basic Usage (Blade)

That's it! 🎉

• First request: Generates thumbnail (~50-200ms)
• Next requests: Cached file served by Nginx (~1-5ms)

🔥 Context-Aware Thumbnails™ (UNIQUE FEATURE!)

The only Laravel package that organizes thumbnails exactly where your content lives!

Why Context Matters

Traditional packages dump all thumbnails into one folder. This causes:

• ❌ Messy filesystem (thousands of files in one directory)
• ❌ Difficult cleanup (delete post, but thumbnails remain)
• ❌ No per-user isolation
• ❌ CDN routing nightmare
• ❌ Slow backups (can't backup specific content types)

Context-Aware Thumbnails™ solves this:

Configuration

Define custom contexts in config/thumbnails.php:

PHP Usage

Model Integration

Benefits

✅ Perfect organization - thumbnails live with their content
✅ Easy cleanup - delete post folder, thumbnails gone
✅ Per-user isolation - great for multi-tenant apps
✅ CDN-friendly - route /user-posts/1/* to User 1's CDN
✅ Faster backups - backup specific content types
✅ Better performance - fewer files per directory

🎨 React / Vue / JavaScript Usage

🌟 UNIQUE FEATURE: We are the ONLY Laravel thumbnail package that provides seamless React/Vue/JavaScript integration with automatic context synchronization! Other packages only work with Blade.

IMPORTANT: For React/Vue apps, you need to generate a JavaScript helper that mirrors your PHP config.

Step 1: Generate JS Helper

This creates resources/js/utils/thumbnails.js with your contexts from config/thumbnails.php.

Run this command whenever you:

• Change config/thumbnails.php
• Add new contexts
• Change filename patterns

Step 2: Import in React/Vue

✅ YES, the import is REQUIRED! Without it, your React/Vue components won't have thumbnail URLs.

Available Functions

✅ Full Feature Parity with PHP

JavaScript helper supports ALL PHP features:

• ✅ Context-Aware paths - Organized by user/post/album
• ✅ Resize methods - crop, fit, resize
• ✅ Modern formats - webp, avif, jpg, png
• ✅ Quality control - 1-100
• ✅ Smart Crop - AI energy detection (v2.0+)
• ✅ On-demand generation - Middleware handles 404

Example with all options:

PHP Backend Setup for React

In your PHP accessor (e.g., UserPost.php):

React will:

1. Call getThumbnailUrl(media.path, 'small')
2. Build URL: /storage/user-posts/1/12/thumbnails/img_thumb_small.jpg
3. Browser requests thumbnail
4. 404 on first request → middleware generates thumbnail
5. 200 on next requests → cached file served by Nginx

Workflow

Vue Example

📦 Benefits

1. ✅ Automatic Cleanup - Delete post folder = all thumbnails gone
2. ✅ Per-User Isolation - Easy permissions & backups per user
3. ✅ CDN Routing - Route different contexts to different CDNs
4. ✅ Performance - Fewer files per directory = faster filesystem
5. ✅ Organization - Find any thumbnail instantly
6. ✅ Scalability - No "one folder with million files" problem

📐 Resize Methods

Choose how thumbnails should be generated:

1. Resize (Default - Proportional)

• ✅ Preserves aspect ratio
• ✅ No cropping
• ⚠️ Final size may differ slightly from target

Use for: Product images, photos where full content must be visible

2. Crop (Exact Size - Center Crop)

• ✅ Exact dimensions guaranteed
• ✅ Fills entire thumbnail
• ⚠️ May cut edges (center-focused)

Use for: Avatars, thumbnails in grids, cards

3. Fit (Preserve All - Add Padding)

• ✅ Entire image visible
• ✅ Exact dimensions
• ⚠️ May have padding/borders

Use for: Logos, icons, images where nothing can be cut

Visual comparison:

📚 Usage Methods

1. Blade Directive

2. Facade

3. Helper Functions

4. Service Injection

5. JavaScript (Frontend)

⚙️ Configuration

Default Sizes

Drivers

GD (built-in, no extra dependencies)

Imagick (better quality, requires ext-imagick)

Intervention Image (most features, requires package)

Quality & Performance

🎯 Advanced Features

HasThumbnails Trait

Automatically delete thumbnails when model is deleted:

Artisan Commands

Manual Management

🆕 V2.0 New Features

Smart Crop (AI Energy Detection)

Automatically detect the most important part of the image for intelligent cropping:

Usage:

When to use:

• Portrait photos (focuses on face/eyes)
• Product photos (focuses on the product)
• Landscape photos (focuses on horizon/main subject)

Modern Image Formats (AVIF/WebP)

Write thumbnails in a modern format with one setting (3.2.0+):

• source (default) keeps each source's own format — upgrading changes no file name.
• webp / avif convert. A transparent PNG keeps its transparency.
• GIF keeps its format (converting would drop the animation), SVG is not rasterised, and anything the encoder on your server cannot write keeps the source format.
• Switching renames every thumbnail, so the old files become orphans — run php artisan thumbnails:clear afterwards.

Never build a thumbnail name by substituting the source's extension yourself — once format is set, photo.jpg has a thumbnail called photo_thumb_small.webp. Ask the package:

AVIF needs GD built with AVIF support (PHP 8.1+) or the Imagick driver. AVIF sources are decoded as well.

The older formats block (auto_convert, priority) in the published config was never read by the package. It is kept only so existing config files do not change.

🔐 Laravel Native Signed URLs Integration

Version 2.0.18+ uses Laravel's native URL::temporarySignedRoute() for signed URLs instead of custom Facebook-style implementation.

⚙️ Setup

Since 3.0 the package registers /storage/{path} (route name storage.serve) and its controller itself — skip steps 1 and 2 below. They describe the setup of 2.x. Adding your own route replaces the package's, and with it the package's checks (signature, expiry, and since 3.2.0 the refusal of .. in the path). Steps 3 and 4 still apply.

1️⃣ Create StorageController (2.x only — not needed since 3.0)

Create app/Http/Controllers/StorageController.php:

2️⃣ Add Route with Signed Middleware (2.x only — the package registers it since 3.0)

Add to routes/web.php:

⚠️ IMPORTANT: Place this route BEFORE any catch-all routes!

3️⃣ Disable Laravel's Auto-Routes

In config/filesystems.php, set serve => false:

4️⃣ Remove public/storage Symlink

Laravel should route ALL /storage/* requests through the controller:

Why remove it?

• Symlink causes Apache/Nginx to serve files statically (bypassing Laravel)
• Static serving = NO middleware = NO signed URL validation
• Your images would load even with expired URLs! ❌

🎯 Enable Signed URLs

In .env:

Generated URLs:

✨ How It Works

1. original() / thumbnail() helpers generate signed URL using URL::temporarySignedRoute()
2. Browser requests the signed URL
3. The package's StorageFileController validates expires and signature, and refuses any path with a .. segment
4. If valid: the file is served with Cache-Control: public, max-age=<expiration>
5. If invalid/expired: 403

ThumbnailFallback Middleware:

• When a thumbnail doesn't exist (404), the middleware generates it on-demand
• Returns 302 redirect to signed URL (if enabled), or serves the file directly when it was written under the very name that was requested
• A 403 is never answered with a fresh URL (3.2.0+). A 403 means the signature was rejected; regenerating it would turn every expired link back into a working one
• Works perfectly with React/Vue/JavaScript!

🗓️ Stable URLs (stable_window, 3.2.0+)

By default every render stamps the current second into expires, so the same thumbnail gets a different URL on every page view — and the browser can never reuse what it has already downloaded. Turn on the stable window and the URL stays byte-identical for the whole window:

• The expiry is snapped to a window of THUMBNAILS_URL_EXPIRATION seconds, offset per file, so the site's URLs do not all rotate in the same second.
• ⚠️ A URL is then valid for between one and two windows. Choose THUMBNAILS_URL_EXPIRATION with that in mind.
• ⚠️ Enabling it changes every signed URL once. Opt-in until 4.0.

📊 URL Expiration Times

🔒 Security Benefits

• ✅ Prevents hotlinking - Other sites can't steal your bandwidth
• ✅ Time-limited access - Links expire after set time
• ✅ No database required - Stateless validation
• ✅ Laravel native - Uses built-in URL::temporarySignedRoute()
• ✅ Cryptographically secure - HMAC-SHA256 signatures

🐛 Troubleshooting

Images still load after expiration?

• ✅ Check if public/storage symlink exists (delete it!)
• ✅ Verify serve => false in config/filesystems.php
• ✅ Clear cache: php artisan optimize:clear

403 Invalid signature on valid URLs?

• ✅ Check if route is named storage.serve
• ✅ Verify signed middleware is applied
• ✅ Ensure route is placed BEFORE catch-all routes

React/Vue images not loading?

• ✅ Backend must return thumbnail URL (not just path)
• ✅ Example:

Usage with Blade directive:

File size comparison:

• AVIF: ~50% smaller than JPEG (best quality per byte)
• WebP: ~30% smaller than JPEG
• JPG: Original compression

Variants System (Generate Multiple Sizes)

Generate multiple thumbnail sizes at once with preset collections:

Usage:

When to use:

• User avatars (small, medium, large)
• Gallery thumbnails (grid, lightbox, full-screen)
• Responsive images (different screen sizes)

Subdirectory Strategies (Performance at Scale)

Choose how thumbnails are organized on the filesystem:

Performance Benefits:

Why: Operating systems slow down with >1000 files per directory.

Security Validation

Protect against malicious file uploads:

Automatic validation: Package validates all images before processing.

Error Handling Modes

Control how the package behaves when errors occur:

Modes:

• silent (recommended for production): Log error, return original image
• strict (recommended for development): Throw exception
• fallback: Return placeholder image

Example:

Daily Usage Statistics (Privacy-Friendly)

Track thumbnail usage for analytics (commercial license holders only):

What's tracked:

• ✅ Daily usage count (how many thumbnails generated today)
• ✅ Methods used (resize, crop, fit)
• ✅ Popular sizes (which sizes are most used)
• ✅ PHP/Laravel versions
• ✅ Domain (where package is installed)

What's NOT tracked:

• ❌ Individual images (no filenames)
• ❌ User data (no emails, IPs, personal info)
• ❌ Image content (we never see your images)

View statistics: Commercial license holders can view stats at https://howtodraw.pl/developer/licenses

🏗️ How It Works

Architecture

File Structure

Before first request:

After thumbnail request:

💼 Licensing

Choose Your License

Full details: LICENSE.md

Contact for commercial licensing: [email protected]

Why Commercial License?

• 🛠️ Ongoing Development - New features, bug fixes, updates
• 💬 Priority Support - Fast response times
• 📖 Comprehensive Docs - Tutorials, examples, best practices
• 🔒 Security Updates - Critical patches within 24h
• 💼 Business Continuity - SLA for Enterprise customers

🆚 Comparison

📖 Examples

Gallery with Thumbnails

Responsive Images

React Component

🤝 Contributing

This is a commercial package. We welcome:

• 🐛 Bug reports (GitHub Issues)
• 💡 Feature suggestions (GitHub Issues)
• 📖 Documentation improvements (PRs welcome)

Contact: [email protected]

📄 License

Commercial License with free personal tier.

See LICENSE.md for full terms.

💝 Credits

Inspired by:

• Symfony's LiipImagineBundle
• Intervention Image

Built with ❤️ by Moonlight Poland Team

📞 Support

GitHub Issues: https://github.com/Moonlight4000/laravel-thumbnails/issues
Email: [email protected]

⭐ If this package helped you, please star it on GitHub!