PHPackages                             danihidayatx/image-optimizer - 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. danihidayatx/image-optimizer

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

danihidayatx/image-optimizer
============================

Optimize your Filament images before they reach your database. Forked from joshembling/image-optimizer for Filament v4 & v5 support.

v2.2.2(1w ago)3218.1k—2.6%3MITPHPPHP ^8.2CI passing

Since Jan 19Pushed 1w agoCompare

[ Source](https://github.com/danihidayatx/image-optimizer)[ Packagist](https://packagist.org/packages/danihidayatx/image-optimizer)[ Docs](https://github.com/danihidayatx/image-optimizer)[ GitHub Sponsors](https://github.com/danihidayatx)[ RSS](/packages/danihidayatx-image-optimizer/feed)WikiDiscussions main Synced 3d ago

READMEChangelogDependencies (37)Versions (9)Used By (0)

> This package is a fork of [joshembling/image-optimizer](https://github.com/joshembling/image-optimizer), updated to support Filament v4 & v5 and Laravel 12 & 13.

Optimize your Filament images before they reach your database.
==============================================================

[](#optimize-your-filament-images-before-they-reach-your-database)

[![Downloads](https://camo.githubusercontent.com/a09c0a46b44d76a72ec094a3a3031782850621df9252897c41ad73186de7b0ca/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f64616e6968696461796174782f696d6167652d6f7074696d697a65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/danihidayatx/image-optimizer)[![Latest Version on Packagist](https://camo.githubusercontent.com/7d7807315bba7c216a5de989a30368627babd4bb9f63a9d5d09c80a3af668ef9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f64616e6968696461796174782f696d6167652d6f7074696d697a65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/danihidayatx/image-optimizer)

When you currently upload an image using the native Filament component `FileUpload`, the original file is saved without any compression or conversion.

Additionally, if you upload an image and use conversions with `SpatieMediaLibraryFileUpload`, the original file is saved with its corresponding versions provided on your model.

What if you'd rather convert and reduce the image(s) before reaching your database/S3 bucket? Especially in the case where you know you'll never need to save the original image sizes the user has uploaded.

🤳 **This is where Filament Image Optimizer comes in**.

You use the same components as you have been doing and have access to two additional methods for maximum optimization, saving you a lot of disk space in the process. 🎉

Contents
--------

[](#contents)

- [Contents](#contents)
- [Installation](#installation)
- [Usage](#usage)
    - [Optimizing Images](#optimizing-images)
    - [Dynamic Values (Closures)](#dynamic-values-closures)
    - [Resizing Images](#resizing-images)
    - [Combining Methods](#combining-methods)
    - [Multiple Images](#multiple-images)
    - [Examples](#examples)
    - [Debugging](#debugging)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Security Vulnerabilities](#security-vulnerabilities)
- [Credits](#credits)
- [Licence](#license)

Installation
------------

[](#installation)

You can install the package via composer, which works with Filament v3.x, v4.x & v5.x, and Laravel 10, 11, 12 & 13:

```
composer require danihidayatx/image-optimizer
```

Usage
-----

[](#usage)

### Filament version

[](#filament-version)

You must be using [Filament v3.x, v4.x or v5.x](https://filamentphp.com/docs/panels/installation) to have access to this plugin.

PHPLaravel versionFilament versionImage Optimizer version^8.2^10.0, ^11.0, ^12.0, ^13.0^3.2, ^4.0, ^5.0^2.2### Server

[](#server)

[GD Library](https://www.php.net/manual/en/image.installation.php) must be installed on your server to compress images.

To ensure WebP images are previewed correctly in the admin panel, you may need to add the correct mime types to your server configuration.

**Apache Users (.htaccess):**

```
AddType image/webp .webp
```

**Nginx Users:**

Ensure your `mime.types` file includes:

```
image/webp webp;
```

### Optimizing images

[](#optimizing-images)

Before uploading your image, you may choose to optimize it by converting to your chosen format. The file saved to your disk will be the converted version only.

E.g. I want to convert my image to 'webp':

```
use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->image()
    ->optimize('webp'),
```

You can also pass a second parameter to `optimize` to set the quality of the image (0-100). This is useful if you want to compress the image further.

```
use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->image()
    ->optimize('webp', 85),
```

You can do exactly the same using `SpatieMediaLibraryFileUpload`:

```
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
    ->optimize('webp', 85),
```

### Dynamic values (Closures)

[](#dynamic-values-closures)

You may pass a **Closure** to almost any parameter (like `quality`, `resize`, `maxImageWidth`, etc.) to dynamically set values based on form state or logic.

For example, adjusting quality based on a toggle:

```
use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->image()
    ->optimize(
        format: 'webp',
        quality: fn ($get) => $get('high_quality') ? 100 : 50
    ),
```

This also works with `SpatieMediaLibraryFileUpload`:

```
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
    ->optimize(
        format: 'webp',
        quality: fn ($get) => $get('is_premium') ? 100 : 80
    ),
```

### Resizing images

[](#resizing-images)

You may also want to resize an image by passing in a percentage you would like to reduce the image by. This will also maintain aspect ratio.

E.g. I'd like to reduce my image (1280px x 720px) by 50%:

```
use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->image()
    ->resize(50),
```

Uploaded image size is 640px x 360px.

You can do the same using `SpatieMediaLibraryFileUpload`:

```
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
    ->resize(50),
```

### Add maximum width and/or height

[](#add-maximum-width-andor-height)

You can also add a maximum width and/or height to the image. This will resize the image to the maximum width and/or height, maintaining the aspect ratio.

```
use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->image()
    ->maxImageWidth(1024)
    ->maxImageHeight(768),
```

### Combining methods

[](#combining-methods)

You can combine these two methods for maximum optimization.

Tip

Most methods like `resize()`, `maxImageWidth()`, and `maxImageHeight()` also support **Closures**, allowing you to dynamically adjust settings based on form state.

```
use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
	->image()
	->optimize('webp')
	->maxImageWidth(1024)
	->maxImageHeight(768)
	->resize(50),
```

```
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
	->optimize('webp')
	->maxImageWidth(1024)
	->maxImageHeight(768)
    ->resize(50),
```

### Multiple images

[](#multiple-images)

You can also do this with multiple images - all images will be converted to the same format and reduced with the same percentage passed in. Just chain on `multiple()` to your upload:

```
use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->image()
	->multiple()
	->optimize('jpg')
    ->resize(50),
```

```
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
	->multiple()
	->optimize('jpg')
    ->resize(50),
```

### Examples

[](#examples)

[![Before](images/before.jpg)](images/before.jpg)

[![After](images/after.jpg)](images/after.jpg)

### Debugging

[](#debugging)

- If you see a 'not found' exception, including "Method `optimize`" or "Method `resize`", ensure you run `composer update` so that your lock file is in sync with your `composer.json`.
- You might see a 'Waiting for size' message and an infinite loading state on the component and the likely cause of this is a CORS issue. This can be quickly be resolved by ensuring you are serving and upload images from the same domain. Check your Javascript console for more information.

### PHPStan / Static Analysis

[](#phpstan--static-analysis)

Since the methods (`optimize()`, `resize()`, etc.) are registered at runtime using Laravel macros, PHPStan / Larastan might flag them as undefined methods.

This package ships with a PHPStan extension to automatically declare these methods.

#### A. Automatic (Recommended)

[](#a-automatic-recommended)

If your project uses [phpstan/extension-installer](https://github.com/phpstan/extension-installer), the extension will be discovered and loaded automatically. No additional configuration is required.

#### B. Manual

[](#b-manual)

If you do not use the extension installer, you must manually register the extension in your project's `phpstan.neon` (or `phpstan.neon.dist`) file:

```
includes:
    - vendor/danihidayatx/image-optimizer/extension.neon
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Dani Hidayat](https://github.com/danihidayatx)
- [Josh Embling](https://github.com/joshembling)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

55

—

FairBetter than 97% of packages

Maintenance98

Actively maintained with recent releases

Popularity39

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 59.6% 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 ~26 days

Recently: every ~32 days

Total

7

Last Release

7d ago

### Community

Maintainers

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

---

Top Contributors

[![joshembling](https://avatars.githubusercontent.com/u/65712975?v=4)](https://github.com/joshembling "joshembling (81 commits)")[![danihidayatx](https://avatars.githubusercontent.com/u/148239387?v=4)](https://github.com/danihidayatx "danihidayatx (32 commits)")[![valpuia](https://avatars.githubusercontent.com/u/28250303?v=4)](https://github.com/valpuia "valpuia (5 commits)")[![Autive](https://avatars.githubusercontent.com/u/6318898?v=4)](https://github.com/Autive "Autive (4 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)")[![FinnPaes](https://avatars.githubusercontent.com/u/71390226?v=4)](https://github.com/FinnPaes "FinnPaes (2 commits)")[![WillieOng-HK](https://avatars.githubusercontent.com/u/5966527?v=4)](https://github.com/WillieOng-HK "WillieOng-HK (1 commits)")[![cleeimpro](https://avatars.githubusercontent.com/u/46934974?v=4)](https://github.com/cleeimpro "cleeimpro (1 commits)")[![enessvg](https://avatars.githubusercontent.com/u/133034948?v=4)](https://github.com/enessvg "enessvg (1 commits)")[![lucasvieira2902](https://avatars.githubusercontent.com/u/66380573?v=4)](https://github.com/lucasvieira2902 "lucasvieira2902 (1 commits)")[![maytham553-elite](https://avatars.githubusercontent.com/u/171784268?v=4)](https://github.com/maytham553-elite "maytham553-elite (1 commits)")[![SupianIDz](https://avatars.githubusercontent.com/u/37969970?v=4)](https://github.com/SupianIDz "SupianIDz (1 commits)")[![ahmadrio](https://avatars.githubusercontent.com/u/41967704?v=4)](https://github.com/ahmadrio "ahmadrio (1 commits)")

---

Tags

laravelimageimage-optimizeroptimizationfilamentfilamentphpdanihidayatx

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/danihidayatx-image-optimizer/health.svg)

```
[![Health](https://phpackages.com/badges/danihidayatx-image-optimizer/health.svg)](https://phpackages.com/packages/danihidayatx-image-optimizer)
```

###  Alternatives

[codewithdennis/filament-select-tree

The multi-level select field enables you to make single selections from a predefined list of options that are organized into multiple levels or depths.

329530.5k29](/packages/codewithdennis-filament-select-tree)[joshembling/image-optimizer

Optimize your Filament images before they reach your database.

113163.0k12](/packages/joshembling-image-optimizer)[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.8M47](/packages/spatie-laravel-pdf)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.6k](/packages/rawilk-profile-filament-plugin)[stephenjude/filament-jetstream

A Laravel starter kit built with Filament inspired by Jetstream.

17760.2k3](/packages/stephenjude-filament-jetstream)[rawilk/filament-password-input

Enhanced password input component for filament.

52263.4k14](/packages/rawilk-filament-password-input)

PHPackages © 2026

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