PHPackages                             dev-extensions/thumbnail-generator - 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. dev-extensions/thumbnail-generator

ActiveLibrary[Image & Media](/categories/media)

dev-extensions/thumbnail-generator
==================================

Media thumbnails generator plugin

v7.6(7mo ago)0308↓83.3%MITPHP

Since Nov 12Pushed 3mo agoCompare

[ Source](https://github.com/vswb/laravel-thumbnail-generator)[ Packagist](https://packagist.org/packages/dev-extensions/thumbnail-generator)[ RSS](/packages/dev-extensions-thumbnail-generator/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (1)Versions (7)Used By (0)

Thumbnail Generator
===================

[](#thumbnail-generator)

Branches
--------

[](#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
---------

[](#-mục-lục)

- [Cài đặt](#c%C3%A0i-%C4%91%E1%BA%B7t)
- [Tính năng](#t%C3%ADnh-n%C4%83ng)
- [Facade (ThumbnailMedia)](#facade-thumbnailmedia)
- [Route Resize](#route-resize)
- [WebP Optimization](#webp-optimization)
- [Cache](#cache)
- [Sử dụng](#s%E1%BB%AD-d%E1%BB%A5ng)
- [Tùy chỉnh](#t%C3%B9y-ch%E1%BB%89nh)
- [Troubleshooting](#troubleshooting)

---

🚀 Cài đặt
---------

[](#-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í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-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-blade-không-cần-import)

```
{!! ThumbnailMedia::getImageUrl($fileUrl, '300x200') !!}
```

### Sử dụng trong PHP Class

[](#sử-dụng-trong-php-class)

```
use Dev\ThumbnailGenerator\Facades\ThumbnailMediaFacade as ThumbnailMedia;

$imageUrl = ThumbnailMedia::getImageUrl('storage/news/image.jpg', '300x200');
```

---

🔄 Route Resize
--------------

[](#-route-resize)

### URL Pattern

[](#url-pattern)

```
/resize/{slug}?w={width}&h={height}

```

### Parameters

[](#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

[](#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ụ

[](#ví-dụ)

```
/resize/storage/news/image.jpg?w=300&h=200
/resize/storage/uploads/photo.png?w=500
/resize/storage/gallery/image.jpg?h=400

```

---

🎨 WebP Optimization
-------------------

[](#-webp-optimization)

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

### Logic hoạt động

[](#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

[](#đ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ụ

[](#ví-dụ-1)

```
Request: /resize/storage/news/image.jpg?w=300&h=200

Files:
  ✅ storage/news/image.jpg (tồn tại)
  ✅ storage/news/image.webp (tồn tại - từ AppMedia conversion)

Result:
  - Dùng image.webp làm nguồn
  - Encode WebP quality 85
  - Content-Type: image/webp
  - Cache: public/resize/300x200/storage/news/image-{hash}.webp

```

---

💾 Cache
-------

[](#-cache)

### Cache Strategy

[](#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

[](#cache-headers)

```
Cache-Control: public, max-age=31536000, immutable
ETag: "{hash}"
Last-Modified: {timestamp}

```

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

### Auto Delete Thumbnails

[](#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
---------

[](#-sử-dụng)

### Trong Blade Template

[](#trong-blade-template)

```

{!! ThumbnailMedia::getImageUrl($fileUrl, '300x200') !!}

```

### Size Options

[](#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

[](#trong-php-controller)

```
use Dev\ThumbnailGenerator\Facades\ThumbnailMediaFacade as ThumbnailMedia;

class ArticleController extends Controller
{
    public function index()
    {
        $imageUrl = ThumbnailMedia::getImageUrl('storage/news/image.jpg', '300x200');
        return view('articles.index', compact('imageUrl'));
    }
}
```

---

⚙️ Tùy chỉnh
------------

[](#️-tùy-chỉnh)

### WebP Quality

[](#webp-quality)

Mặc định: **85**

Thay đổi trong `PublicController.php`:

```
$encodedImage = $image->encode(new WebpEncoder(quality: 85));
```

### Max Width Limit

[](#max-width-limit)

Mặc định: **1800px**

Thay đổi trong `PublicController.php`:

```
if($size[0] > 1800) {
    $size[0] = 1800;
}
```

### Cache Duration

[](#cache-duration)

Mặc định: **30 ngày**

Thay đổi trong `PublicController.php`:

```
apps_cache_store($metaCacheKey, $size, 60 * 60 * 24 * 30, 'thumbnail_meta');
```

### AppMedia Settings

[](#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 ý
--------

[](#️-lưu-ý)

### File Path

[](#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

[](#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)

- ✅ 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-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
-----------------

[](#-troubleshooting)

### Lỗi: "Route not found"

[](#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"

[](#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

[](#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

[](#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
---------

[](#-license)

This package is part of Laravel CMS project.

---

👥 Support
---------

[](#-support)

For issues and questions, please contact:

---

**Version:** 1.1.0
**Last Updated:** 2025

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance72

Regular maintenance activity

Popularity15

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

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 ~11 days

Total

3

Last Release

207d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c6f3de3d3992647065c443eca835cac3f63e4a257e003367129e216638b98ef2?d=identicon)[vswb](/maintainers/vswb)

### Embed Badge

![Health badge](/badges/dev-extensions-thumbnail-generator/health.svg)

```
[![Health](https://phpackages.com/badges/dev-extensions-thumbnail-generator/health.svg)](https://phpackages.com/packages/dev-extensions-thumbnail-generator)
```

###  Alternatives

[goat1000/svggraph

Generates SVG graphs

135911.1k3](/packages/goat1000-svggraph)[gravatarphp/gravatar

Gravatar URL builder which is most commonly called as a Gravatar library

16653.6k2](/packages/gravatarphp-gravatar)[rsoury/wp-imgix

Rewrites WordPress image URLs to use ImgIX

167.2k](/packages/rsoury-wp-imgix)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)