Download the PHP package dev-extensions/thumbnail-generator without Composer

Thumbnail Generator

Branches

• 📦 lte.6x-is_dev: sử dụng cho các phiên bản CMS <=6.x và namespace hệ thống dưới dạng Dev\\
• 📦 lte.6x-is_platform: sử dụng cho các phiên bản CMS <=6.x và namespace hệ thống dưới dạng Platform\\
• 📦 v7x: sử dụng cho các phiên bản CMS >=7.x và namespace hệ thống lúc này luôn luôn dưới dạng Dev\\

Package tự động tạo và tối ưu thumbnail images với hỗ trợ WebP cho Laravel CMS.

📋 Mục lục

• Cài đặt
• Tính năng
• Facade (ThumbnailMedia)
• Route Resize
• WebP Optimization
• Cache
• Sử dụng
• Tùy chỉnh
• Troubleshooting

🚀 Cài đặt

1. Copy package vào thư mục: dev-extensions/libs/thumbnail-generator
2. Đảm bảo package đã được autoload trong composer.json
3. Service provider tự động được đăng ký: Dev\ThumbnailGenerator\Providers\ThumbnailGeneratorServiceProvider

✨ Tính năng

• ✅ Tự động resize với query params ?w={width}&h={height}
• ✅ Force WebP output cho tất cả format (jpg, jpeg, png, gif, webp) - tối ưu Google PageSpeed
• ✅ WebP source priority - tự động dùng file .webp nếu có (từ AppMedia conversion)
• ✅ Cache thông minh - cache trên disk với ETag và Last-Modified headers
• ✅ Auto cleanup - tự động xóa thumbnails khi xóa file trong CMS
• ✅ Tích hợp AppMedia - sử dụng tất cả tính năng mới (WebP conversion, auto resize, validation, events)

🎯 Facade (ThumbnailMedia)

Facade đã được tự động đăng ký và bind vào service container. Không cần cấu hình thêm.

Sử dụng trong Blade (không cần import)

Sử dụng trong PHP Class

🔄 Route Resize

URL Pattern

Parameters

• {slug}: Đường dẫn file ảnh từ thư mục public (ví dụ: storage/news/image.jpg)
• w: Chiều rộng (pixels, optional - tự động tính nếu không có)
• h: Chiều cao (pixels, optional - tự động tính nếu không có)

Features

• ✅ Hỗ trợ format: jpg, jpeg, png, webp, gif
• ✅ Tự động giới hạn max-width: 1800px
• ✅ Tự động tính tỉ lệ aspect ratio
• ✅ Force output WebP cho tất cả format (tối ưu performance)

Ví dụ

🎨 WebP Optimization

Package tự động force output WebP cho tất cả image formats để tối ưu Google PageSpeed Insights.

Logic hoạt động

1. Request: /resize/storage/news/image.jpg?w=300&h=200
2. Check WebP source: Tự động tìm file storage/news/image.webp (nếu có từ AppMedia conversion)
3. Nếu WebP source TỒN TẠI:
   • ✅ Dùng file WebP làm nguồn (tốt hơn)
   • ✅ Encode lại thành WebP với quality 85
   • ✅ Set Content-Type: image/webp
4. Nếu WebP source KHÔNG TỒN TẠI:
   • ✅ Dùng file gốc (jpg/png/jpeg)
   • ✅ Encode thành WebP với quality 85
   • ✅ Set Content-Type: image/webp
5. Auto cleanup: Tự động xóa file cache cũ (jpg/jpeg/png) khi tạo WebP mới

Điều kiện

• ✅ Force WebP cho: jpg, jpeg, png, gif, webp
• ✅ WebP source priority: Nếu có file .webp cùng tên, dùng làm nguồn
• ✅ Content-Type đúng: Tự động detect extension thực tế và set Content-Type tương ứng

Ví dụ

💾 Cache

Cache Strategy

• Disk cache: Thumbnail được lưu tại public/resize/{width}x{height}/{subPath}/{normalized}-{hash}.webp
• In-memory meta cache: Kích thước ảnh gốc được cache 30 ngày để giảm getimagesize()
• Auto Invalidate: Tự động clear khi file gốc thay đổi (dựa trên filemtime)
• Concurrency-safe: Sử dụng file lock để tránh generate cùng lúc
• Auto cleanup: Tự động xóa file cache cũ khi tạo WebP mới

Cache Headers

Headers này giúp tối ưu Google PageSpeed Insights và browser caching.

Auto Delete Thumbnails

Khi xóa file trong CMS:

• ✅ Tự động xóa thumbnails trong storage (từ AppMedia)
• ✅ Tự động xóa thumbnails trong public/resize/ (từ ThumbnailGenerator)
• ✅ Tự động cleanup empty directories

🎨 Sử dụng

Trong Blade Template

Size Options

• '300x200': Kích thước cố định
• '300xauto': Width cố định, height tự động tính
• 'autox200': Height cố định, width tự động tính

Trong PHP Controller

⚙️ Tùy chỉnh

WebP Quality

Mặc định: 85

Thay đổi trong PublicController.php:

Max Width Limit

Mặc định: 1800px

Thay đổi trong PublicController.php:

Cache Duration

Mặc định: 30 ngày

Thay đổi trong PublicController.php:

AppMedia Settings

Package tích hợp với AppMedia, sử dụng các settings từ admin panel:

• media_convert_image_to_webp: Tự động convert upload thành WebP
• media_reduce_large_image_size: Tự động resize hình lớn
• media_image_max_width: Max width cho resize
• media_image_max_height: Max height cho resize

⚠️ Lưu ý

File Path

• ✅ File ảnh phải nằm trong thư mục public hoặc có symbolic link
• ✅ Đường dẫn phải bắt đầu từ storage/ hoặc relative path từ public

WebP Optimization

• ✅ Force WebP cho tất cả format (jpg, jpeg, png, gif, webp)
• ✅ Tự động ưu tiên file .webp nếu có (từ AppMedia conversion)
• ✅ Tự động xóa file cache cũ khi tạo WebP mới

Cache

• ✅ Cache sẽ tự động clear khi file gốc thay đổi (dựa trên filemtime)
• ✅ Cache key bao gồm cả format để tránh conflict
• ✅ Cache riêng biệt cho từng kích thước
• ✅ Tự động cleanup khi xóa file trong CMS

ThumbnailMedia Integration

• ✅ ThumbnailMedia extends AppMedia và sử dụng tất cả tính năng mới
• ✅ handleUpload() gọi parent::handleUpload() để sử dụng WebP conversion, auto resize, validation từ AppMedia
• ✅ deleteThumbnails() override để xóa cả thumbnails trong public/resize/

🔧 Troubleshooting

Lỗi: "Route not found"

Nguyên nhân: Route chưa được register

Giải pháp: Đảm bảo service provider đã được load và routes được register

Lỗi: "File not found"

Nguyên nhân: File không tồn tại trong public path

Giải pháp:

• Kiểm tra file có tồn tại: public_path('storage/news/image.jpg')
• Kiểm tra symbolic link: php artisan storage:link

Response trả về Content-Type sai

Nguyên nhân: File cache cũ (jpg) đã tồn tại

Giải pháp:

• Xóa cache cũ: rm -rf public/resize/*
• Request lại để tạo cache WebP mới

WebP không được serve

Kiểm tra:

1. File WebP có được tạo trong public/resize/?
2. Content-Type header có đúng image/webp?
3. File cache cũ (jpg) đã bị xóa chưa?

📄 License

This package is part of Laravel CMS project.

👥 Support

For issues and questions, please contact: [email protected]

Version: 1.1.0
Last Updated: 2025