Filament Image Optimizer

https://github.com/danihidayatx/image-optimizer
Admin
Filament Image Optimizer is a package that optimizes and resizes images uploaded via Filament's...
Tokens:25,909
Snippets:176
Trust Score:6
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### resize usage examples

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Two examples of using the resize macro: a static percentage and a dynamic closure.

```php
// Reduce every uploaded image by 50%
FileUpload::make('attachment')
    ->image()
    ->resize(50);
```

```php
// Dynamic percentage (Closure)
SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
    ->resize(fn () => 50);
```

--------------------------------

### optimize usage examples

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Three usage examples: convert to WebP with default quality, convert to JPEG quality 85, and dynamic quality via Closure.

```php
// Convert to WebP with default quality
FileUpload::make('attachment')
    ->image()
    ->optimize('webp');
```

```php
// Convert to JPEG quality 85
FileUpload::make('attachment')
    ->image()
    ->optimize('jpeg', 85);
```

```php
// Dynamic quality based on form state (Closure)
FileUpload::make('attachment')
    ->image()
    ->optimize(
        format: 'webp',
        quality: fn ($get) => $get('high_quality') ? 100 : 50,
    );
```

--------------------------------

### Install via Composer

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Install the package with Composer. Requires Filament v3.x, v4.x or v5.x and Laravel 10-13.

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

--------------------------------

### Resize Image by Percentage (FileUpload)

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Resize image by percentage, maintaining aspect ratio. Example reduces 1280x720 to 640x360.

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

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

--------------------------------

### maxImageWidth usage example

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Example of using the maxImageWidth macro to set a maximum width of 1024 pixels.

```php
FileUpload::make('attachment')
    ->image()
    ->maxImageWidth(1024);
```

--------------------------------

### customHeaders usage example

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Shows how to use the `customHeaders` macro on a `SpatieMediaLibraryFileUpload` instance, passing an associative array (e.g., `CacheControl`) to the file-add operation.

```php
SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
    ->optimize('webp')
    ->customHeaders([
        'CacheControl' => 'max-age=604800',
    ]);
```

--------------------------------

### mediaName usage example

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Example of using the mediaName macro on a SpatieMediaLibraryFileUpload instance to set the media item name to 'profile-picture'.

```php
SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
    ->optimize('webp')
    ->mediaName('profile-picture');
```

--------------------------------

### maxImageHeight usage example

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Example of using the maxImageHeight macro on a FileUpload instance to set a maximum height of 768 pixels.

```php
FileUpload::make('attachment')
    ->image()
    ->maxImageHeight(768);
```

--------------------------------

### ImageProcessor::process($source, array $settings): string

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-processor.md

Processes an image source (raw binary content or Livewire temporary uploaded file) according to the provided settings, returning the encoded image as raw binary content. It automatically selects the appropriate Intervention Image version (v2 or v3) based on the installed library.

```APIDOC
## ImageProcessor::process($source, array $settings): string

### Description
Processes an image source (raw binary content or Livewire temporary uploaded file) according to the provided settings, returning the encoded image as raw binary content. It automatically selects the appropriate Intervention Image version (v2 or v3) based on the installed library.

### Method
Static method call

### Signature
```php
public static function process($source, array $settings): string
```

### Parameters
- **$source** (string | Livewire\Features\SupportFileUploads\TemporaryUploadedFile) - Required - Raw image binary content (as string) or a Livewire temporary uploaded file. A TemporaryUploadedFile is resolved to its real path before decoding (i.e., $source->getRealPath()).
- **$settings** (array) - Required - Settings array, inline-expanded below.

### Settings Array
- **format** (string|null) - Optional - Target output format. One of `webp`, `jpeg`, `jpg`, `png`, `gif`, `bmp`. `null`/falsy → decode/re-encode in the original format.
- **resize** (int|null) - Optional - Reduction percentage. Target for the dominant axis = `dimension - (dimension * $resize / 100)`. `null`/falsy → no percentage resize.
- **max_width** (int|null) - Optional - Cap source width only if `image->width() > max_width`.
- **max_height** (int|null) - Optional - Cap source height only if `image->height() > max_height`.
- **quality** (int|null) - Optional - Encoding quality 0–100. Defaulting rule: when `$format` is set and quality is `null`, quality becomes `70` iff format is `jpeg` or `jpg`; otherwise it stays `null` (library default quality is used, e.g., 90 in v2 `encode()`).

### Dispatcher Logic
- If `class_exists('Intervention\Image\ImageManagerStatic')` → v2 path (`processV2`).
- Otherwise → v3 path (`processV3`).

### Return
`string` — the encoded image as raw binary content (safe to pass to `Storage::disk()->put()` or `file_put_contents()`). The return is the *encoded bytes*, not a path.

### Throws
- (Intervention) `Intervention\Image\Exception\DecoderException` - If `$source` cannot be decoded as an image.
- (Intervention) GD/Imagick driver exceptions - If GD or Imagick extension missing/unavailable at encode time.

### Examples
Basic call — direct processing of raw binary content:

```php
use DaniHidayatX\ImageOptimizer\ImageProcessor;

$binary = file_get_contents('/tmp/original.jpg');

$webp = ImageProcessor::process($binary, [
    'format'     => 'webp',
    'resize'     => null,
    'max_width'  => null,
    'max_height' => null,
    'quality'    => null,
]);

Storage::disk('public')->put('optimized/photo.webp', $webp);
```

Non-trivial call — percentage resize + caps + explicit quality (and error handling around decode failures):

```php
use DaniHidayatX\ImageOptimizer\ImageProcessor;
use Intervention\Image\Exception\DecoderException;

try {
    $content = ImageProcessor::process($file->get(), [
        'format'     => 'jpeg',
        'resize'     => 50,
        'max_width'  => 1024,
        'max_height' => 768,
        'quality'    => 85,
    ]);
} catch (DecoderException) {
    // source was not a decodable image — fall back to storing the original
    return $file->storeAs('uploads', $file->getClientOriginalName(), 'public');
}
```
```

--------------------------------

### ensureOptimizerHook macro registration in ImageOptimizerServiceProvider

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-processing.md

Registers the ensureOptimizerHook macro on FileUpload. Installs the saveUploadedFileUsing callback once per component, guarded by the hasOptimizerHook property. The callback dispatches to processAndStoreSpatie for Spatie components, otherwise to processAndStoreImage.

```php
FileUpload::macro('ensureOptimizerHook', function () {
    if ($this->hasOptimizerHook ?? false) {
        return;
    }
    $this->hasOptimizerHook = true;

    $this->saveUploadedFileUsing(function (FileUpload $component, TemporaryUploadedFile $file, ?Model $record = null) {
        if ($component->isSpatieComponent()) {
            return $component->processAndStoreSpatie($file, $record);
        }

        return $component->processAndStoreImage($file);
    });
});
```

--------------------------------

### packageBooted method

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-optimizer-service-provider.md

Called after package boot; runs registerMacros() and publishStubs().

```php
public function packageBooted(): void
{
    $this->registerMacros();
    $this->publishStubs();
}
```

--------------------------------

### Using ImageProcessor directly vs facade

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-optimizer-facade.md

Shows the recommended usage with ImageProcessor::process() and the non-resolvable facade call. The facade will throw BindingResolutionException because the 'image-optimizer' binding is never registered.

```php
use DaniHidayatX\ImageOptimizer\ImageProcessor;

ImageProcessor::process($binary, ['format' => 'webp']);        // OK
ImageOptimizer::process($binary, ['format' => 'webp']);        // not resolvable — binding 'image-optimizer' is never bound
```

--------------------------------

### configurePackage method

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-optimizer-service-provider.md

Registers the package name, config file, and translations. Called by the base class.

```php
public function configurePackage(Package $package): void
{
    $package->name(static::$name)
        ->hasConfigFile()
        ->hasTranslations();
}
```

--------------------------------

### Combine Optimization Methods (FileUpload)

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Combine optimize, maxImageWidth, maxImageHeight, and resize for maximum optimization.

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

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

--------------------------------

### Optimize with SpatieMediaLibraryFileUpload

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Same optimization with quality using SpatieMediaLibraryFileUpload component.

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

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

--------------------------------

### Optimize to WebP with Quality Parameter

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Set image quality (0-100) as second parameter to optimize for further compression.

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

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

--------------------------------

### Combine Optimization Methods (SpatieMediaLibraryFileUpload)

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Same combined methods using SpatieMediaLibraryFileUpload.

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

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

--------------------------------

### Dynamic Quality with Closure (SpatieMediaLibraryFileUpload)

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Same dynamic quality using SpatieMediaLibraryFileUpload with a Closure.

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

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

--------------------------------

### PHPStan extension entry point: extension.neon

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/configuration.md

Registers the stub file that declares macro methods for static analysis.

```neon
parameters:
    stubFiles:
        - stubs/FileUpload.stub.php
```

--------------------------------

### Optimize Multiple Images (SpatieMediaLibraryFileUpload)

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Same multiple image optimization using SpatieMediaLibraryFileUpload.

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

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

--------------------------------

### Publish config tag command

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/configuration.md

Optional command to publish the config file under the 'config' tag. Has no effect because the config is empty.

```bash
php artisan vendor:publish --tag=config
```

--------------------------------

### Resize Image by Percentage (SpatieMediaLibraryFileUpload)

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Same resize functionality using SpatieMediaLibraryFileUpload.

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

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

--------------------------------

### publishStubs method

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-optimizer-service-provider.md

Publishes stub files to base_path('stubs/image-optimizer') under the 'image-optimizer-stubs' tag when running in console.

```php
protected function publishStubs(): void
{
    if (app()->runningInConsole()) {
        $filesystem = app(Filesystem::class);
        $stubsPath = __DIR__ . '/../stubs/';
        if ($filesystem->exists($stubsPath)) {
            foreach ($filesystem->files($stubsPath) as $file) {
                $this->publishes([
                    $file->getRealPath() => base_path("stubs/image-optimizer/{$file->getFilename()}"),
                ], 'image-optimizer-stubs');
            }
        }
    }
}
```

--------------------------------

### Optimize Multiple Images (FileUpload)

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Apply optimization and resize to multiple images using multiple() method.

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

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

--------------------------------

### Publishing command for stubs

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-optimizer-service-provider.md

Command to publish the package stubs using the 'image-optimizer-stubs' tag.

```bash
php artisan vendor:publish --tag=image-optimizer-stubs
```

--------------------------------

### Config file: config/image-optimizer.php

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/configuration.md

Shipped config file that returns an empty array. No options are defined or consumed; publishing it has no effect.

```php
<?php

// config for DaniHidayatX/ImageOptimizer
return [

];
```

--------------------------------

### Optimize to WebP with FileUpload

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Convert uploaded image to WebP format using the optimize method on FileUpload.

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

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

--------------------------------

### process() with resize, caps, quality, and DecoderException handling

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-processor.md

Non-trivial call applying a 50% resize, max width 1024, max height 768, and explicit quality 85. Wraps the call in a try/catch for DecoderException, falling back to storing the original file when the source is not decodable.

```php
use DaniHidayatX\ImageOptimizer\ImageProcessor;
use Intervention\Image\Exception\DecoderException;

try {
    $content = ImageProcessor::process($file->get(), [
        'format'     => 'jpeg',
        'resize'     => 50,
        'max_width'  => 1024,
        'max_height' => 768,
        'quality'    => 85,
    ]);
} catch (DecoderException) {
    // source was not a decodable image — fall back to storing the original
    return $file->storeAs('uploads', $file->getClientOriginalName(), 'public');
}
```

--------------------------------

### Translations file: resources/lang/en/image-optimizer.php

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/configuration.md

Empty translations array. No translation keys are shipped or referenced.

```php
<?php

// translations for DaniHidayatX/ImageOptimizer
return [
    //
];
```

--------------------------------

### Dynamic Quality with Closure (FileUpload)

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Use a Closure to set quality dynamically based on form state (e.g., a toggle).

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

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

--------------------------------

### Manual provider registration in config/app.php

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-optimizer-service-provider.md

Register the service provider manually when auto-discovery is disabled. Add the provider class to the 'providers' array in config/app.php.

```php
// config/app.php (only needed if auto-discovery is disabled)
'providers' => [
    // ...
    DaniHidayatX\ImageOptimizer\ImageOptimizerServiceProvider::class,
],
```

--------------------------------

### Basic process() call with raw binary content

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-processor.md

Direct processing of raw binary content. Reads a JPEG file, converts to WebP with default settings (no resize, no caps, no quality), and stores the result to the public disk. The returned value is raw encoded bytes, not a path.

```php
use DaniHidayatX\ImageOptimizer\ImageProcessor;

$binary = file_get_contents('/tmp/original.jpg');

$webp = ImageProcessor::process($binary, [
    'format'     => 'webp',
    'resize'     => null,
    'max_width'  => null,
    'max_height' => null,
    'quality'    => null,
]);

Storage::disk('public')->put('optimized/photo.webp', $webp);
```

--------------------------------

### optimize

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Configures image optimization for a FileUpload instance. Sets the output format and quality, and ensures the optimizer hook is registered. Returns the FileUpload instance for fluent chaining.

```APIDOC
## optimize

### Description
Configures image optimization for a FileUpload instance. Sets the output format and quality, and ensures the optimizer hook is registered. Returns the FileUpload instance for fluent chaining.

### Method
Macro (PHP)

### Endpoint
FileUpload::optimize()

### Parameters
#### Arguments
- **$format** (string|Closure|null) - Optional - Default: `'webp'` - Output format: `webp`, `jpeg`/`jpg`, `png`, `gif`, `bmp`. `jpg` is normalized to `jpeg` in the v3 path; the v2 path passes it verbatim to `encode()`. `null` disables conversion (encoding stays the original format).
- **$quality** (int|Closure|null) - Optional - Default: `null` - Quality 0–100. `null` uses the processor default: `70` for jpeg/jpg when a format is set, otherwise the Intervention default.

### Return Value
- **$this** (FileUpload) - Fluent.

### Default Quality Behavior
When `$format` is truthy and `$quality` is `null`, quality defaults to `70` for `jpeg`/`jpg` formats only.

### Request Example
```php
// Convert to WebP with default quality
FileUpload::make('attachment')
    ->image()
    ->optimize('webp');

// Convert to JPEG quality 85
FileUpload::make('attachment')
    ->image()
    ->optimize('jpeg', 85);

// Dynamic quality based on form state (Closure)
FileUpload::make('attachment')
    ->image()
    ->optimize(
        format: 'webp',
        quality: fn ($get) => $get('high_quality') ? 100 : 50,
    );
```

### Response
No response body; returns the FileUpload instance.
```

--------------------------------

### Combined usage pattern

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Demonstrates a combined usage of multiple macros on a `FileUpload` component: `optimize`, `resize`, `maxImageWidth`, and `maxImageHeight`. The `multiple()` method applies the same treatment to every uploaded file.

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

FileUpload::make('attachment')
    ->image()
    ->multiple()                 // every uploaded file gets the same treatment
    ->optimize('webp')
    ->resize(50)
    ->maxImageWidth(1024)
    ->maxImageHeight(768);
```

--------------------------------

### FileUpload::processAndStoreSpatie()

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/overview.md

Runtime macro registered on Filament's FileUpload component. It processes and stores a Spatie media library image.

```APIDOC
## FileUpload::processAndStoreSpatie()

### Description
Runtime macro registered on Filament's FileUpload component. It processes and stores a Spatie media library image.

### Method
processAndStoreSpatie()

### Parameters
No parameters documented.

### Response
No response documented.
```

--------------------------------

### optimize macro docblock

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Docblock for the optimize macro method, showing the signature with format and quality parameters.

```php
/**
 * @method $this optimize(string|\Closure|null $format = 'webp', int|\Closure|null $quality = null)
 */
```

--------------------------------

### Set Maximum Width and Height

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Resize image to maximum width and height while maintaining aspect ratio.

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

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

--------------------------------

### Chain FileUpload macros: optimize, resize, maxImageWidth, maxImageHeight

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Shows fluent chaining of the four settings macros on a FileUpload component. Each macro stores its argument into the component's dynamic 'imageOptimization' array property and returns $this. Parameters may be Closures receiving Filament's standard evaluation context.

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

--------------------------------

### FileUpload::processAndStoreImage()

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/overview.md

Runtime macro registered on Filament's FileUpload component. It processes and stores an image.

```APIDOC
## FileUpload::processAndStoreImage()

### Description
Runtime macro registered on Filament's FileUpload component. It processes and stores an image.

### Method
processAndStoreImage()

### Parameters
No parameters documented.

### Response
No response documented.
```

--------------------------------

### ImageProcessor::process()

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/overview.md

Public static method to process an image. It is part of the Image Optimizer package's public API surface.

```APIDOC
## ImageProcessor::process()

### Description
Public static method to process an image. It is part of the Image Optimizer package's public API surface.

### Method
process()

### Parameters
No parameters documented.

### Response
No response documented.
```

--------------------------------

### resize macro PHPDoc

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

PHPDoc annotation for the resize macro, showing the method signature with a default percent of 50.

```php
/**
 * @method $this resize(int|\Closure|null $percent = 50)
 */
```

--------------------------------

### maxImageWidth macro PHPDoc

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

PHPDoc annotation for the maxImageWidth macro, showing the method signature with a required width parameter.

```php
/**
 * @method $this maxImageWidth(int|\Closure|null $width)
 */
```

--------------------------------

### process() method signature from src/ImageProcessor.php

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-processor.md

Full signature of the static process() method. Dispatches to processV2 if Intervention Image v2 (ImageManagerStatic) exists, otherwise to processV3. Extracts settings for format, resize, max_width, max_height, and quality, applying a default quality of 70 for jpeg/jpg when format is set and quality is null.

```php
public static function process($source, array $settings): string
{
    $format = $settings['format'] ?? null;
    $resize = $settings['resize'] ?? null;
    $maxWidth = $settings['max_width'] ?? null;
    $maxHeight = $settings['max_height'] ?? null;
    $quality = $settings['quality'] ?? null;

    if ($format) {
        $quality = $quality ?? ($format === 'jpeg' || $format === 'jpg' ? 70 : null);
    }

    if (class_exists('Intervention\Image\ImageManagerStatic')) {
        return self::processV2($source, $format, $resize, $maxWidth, $maxHeight, $quality);
    }

    return self::processV3($source, $format, $resize, $maxWidth, $maxHeight, $quality);
}
```

--------------------------------

### Class declaration for ImageOptimizerServiceProvider

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-optimizer-service-provider.md

Defines the service provider class extending PackageServiceProvider with a static $name property set to 'image-optimizer'.

```php
class ImageOptimizerServiceProvider extends PackageServiceProvider
{
    public static string $name = 'image-optimizer';
}
```

--------------------------------

### Alias registration in composer.json

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-optimizer-facade.md

Maps the facade class to the alias 'ImageOptimizer' in Laravel's auto-discovery. This makes ImageOptimizer::method() available when auto-discovery is enabled.

```json
"aliases": {
    "ImageOptimizer": "DaniHidayatX\\ImageOptimizer\\Facades\\ImageOptimizer"
}
```

--------------------------------

### processAndStoreSpatie method signature

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-processing.md

Declares the method signature for the Spatie Media Library pipeline macro. The method accepts a Livewire temporary uploaded file and an optional Eloquent model, returning the media UUID or null.

```php
/**
 * @method string|null processAndStoreSpatie(\Livewire\Features\SupportFileUploads\TemporaryUploadedFile $file, ?\Illuminate\Database\Eloquent\Model $record)
 */
```

--------------------------------

### ImageOptimizer facade class declaration

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-optimizer-facade.md

The facade class extends Laravel's Facade base class and defines the accessor 'image-optimizer'. This class is not backed by a resolvable implementation in the current source.

```php
<?php

namespace DaniHidayatX\ImageOptimizer\Facades;

use Illuminate\Support\Facades\Facade;

/**
 * @see \DaniHidayatX\ImageOptimizer\ImageOptimizer
 */
class ImageOptimizer extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'image-optimizer';
    }
}
```

--------------------------------

### processAndStoreSpatie macro implementation

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-processing.md

Registers the 'processAndStoreSpatie' macro on FileUpload. Optimizes the file, writes it to a temp file, and adds it to the record's Media Library. Returns the media UUID or null if the record is missing or lacks addMedia(). The temp file is always cleaned up in a finally block.

```php
FileUpload::macro('processAndStoreSpatie', function (TemporaryUploadedFile $file, ?Model $record) {
    /** @var SpatieMediaLibraryFileUpload $component */
    $component = $this;
    if (! $record || ! method_exists($record, 'addMedia')) {
        return null;
    }
    // ... evaluate settings (format, resize, max_width, max_height, quality)
    //     identical to processAndStoreImage — see source lines 196–204
    $tempPath = tempnam(sys_get_temp_dir(), 'optimized-image-');
    file_put_contents($tempPath, $content);
    $mediaAdder = $record->addMedia($tempPath);

    if ($name = $component->evaluate($settings['media_name'] ?? null)) {
        $mediaAdder->usingName($name);
    } else {
        $mediaAdder->usingName(pathinfo($file->getClientOriginalName(), PATHINFO_FILENAME));
    }

    if ($headers = $component->evaluate($settings['custom_headers'] ?? null)) {
        $mediaAdder->addCustomHeaders($headers);
    }

    $mediaAdder->usingFileName($filename);

    if (method_exists($component, 'getCustomProperties')) {
        $mediaAdder->withCustomProperties($component->getCustomProperties($file));
    }
    if (method_exists($component, 'getManipulations')) {
        $mediaAdder->withManipulations($component->getManipulations());
    }
    if (method_exists($component, 'getConversionsDisk') && $disk = $component->getConversionsDisk()) {
        $mediaAdder->storingConversionsOnDisk($disk);
    }
    if (method_exists($component, 'hasResponsiveImages') && $component->hasResponsiveImages()) {
        $mediaAdder->withResponsiveImages();
    }

    try {
        $media = $mediaAdder->toMediaCollection($component->getCollection(), $component->getDiskName());
    } finally {
        if (file_exists($tempPath)) {
            unlink($tempPath);
        }
    }

    return $media->getAttributeValue('uuid');
});
```

--------------------------------

### FileUpload::mediaName()

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/overview.md

Runtime macro registered on Filament's FileUpload component (Spatie). It sets the media name.

```APIDOC
## FileUpload::mediaName()

### Description
Runtime macro registered on Filament's FileUpload component (Spatie). It sets the media name.

### Method
mediaName()

### Parameters
No parameters documented.

### Response
Returns $this for fluent chaining.
```

--------------------------------

### FileUpload::resize()

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/overview.md

Runtime macro registered on Filament's FileUpload component. It is used to resize an uploaded image.

```APIDOC
## FileUpload::resize()

### Description
Runtime macro registered on Filament's FileUpload component. It is used to resize an uploaded image.

### Method
resize()

### Parameters
No parameters documented.

### Response
Returns $this for fluent chaining.
```

--------------------------------

### resize macro registration

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Registers the resize macro on FileUpload, storing the percent in imageOptimization and ensuring the optimizer hook.

```php
FileUpload::macro('resize', function (int | Closure | null $percent = 50) {
    $this->imageOptimization = $this->imageOptimization ?? [];
    $this->imageOptimization['resize'] = $percent;
    $this->ensureOptimizerHook();

    return $this;
});
```

--------------------------------

### resize

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Registers a macro on FileUpload to resize uploaded images by a percentage. The percentage is applied to the larger dimension, preserving aspect ratio, and returns the instance for fluent chaining.

```APIDOC
## resize

### Description
Registers a macro on FileUpload to resize uploaded images by a percentage. The percentage is applied to the larger dimension, preserving aspect ratio, and returns the instance for fluent chaining.

### Method
Macro (PHP)

### Parameters
- **$percent** (int|Closure|null) - Optional - Default: `50` - Reduction percentage. The processor computes the target as `dimension - (dimension * $percent / 100)` along the larger axis, so `resize(50)` halves the image (e.g., 1280×720 → 640×360). `null` disables resizing.

### Return
`$this` (FileUpload) - fluent.

### Example
```php
// Reduce every uploaded image by 50%
FileUpload::make('attachment')
    ->image()
    ->resize(50);

// Dynamic percentage (Closure)
SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
    ->resize(fn () => 50);
```
```

--------------------------------

### processV3 method for intervention/image v3 API

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-processor.md

Protected static method that processes an image using the intervention/image v3 API. Selects Imagick driver if available, otherwise GD. Converts TemporaryUploadedFile sources to real path, scales image based on max dimensions or resize percentage, and encodes to specified format with quality where supported.

```php
protected static function processV3($source, $format, $resize, $maxWidth, $maxHeight, $quality): string
{
    $driver = extension_loaded('imagick') && class_exists('\Intervention\Image\Drivers\Imagick\Driver')
        ? new Driver
        : new \Intervention\Image\Drivers\Gd\Driver;

    $manager = new ImageManager($driver);

    if ($source instanceof TemporaryUploadedFile) {
        $source = $source->getRealPath();
    }

    $image = $manager->read($source);

    $calcWidth = null;
    $calcHeight = null;

    if ($maxWidth && $image->width() > $maxWidth) {
        $calcWidth = $maxWidth;
    }

    if ($maxHeight && $image->height() > $maxHeight) {
        $calcHeight = $maxHeight;
    }

    if ($resize) {
        if ($image->height() > $image->width()) {
            $calcHeight = $image->height() - ($image->height() * ($resize / 100));
        } else {
            $calcWidth = $image->width() - ($image->width() * ($resize / 100));
        }
    }

    if ($calcWidth || $calcHeight) {
        $image->scale($calcWidth, $calcHeight);
    }

    if ($format) {
        $format = strtolower($format);

        if ($format === 'jpg') {
            $format = 'jpeg';
        }

        if ($format === 'webp') {
            return (string) ($quality ? $image->toWebp($quality) : $image->toWebp());
        }
        if ($format === 'jpeg') {
            return (string) ($quality ? $image->toJpeg($quality) : $image->toJpeg());
        }
        if ($format === 'png') {
            return (string) $image->toPng();
        }
        if ($format === 'gif') {
            return (string) $image->toGif();
        }
        if ($format === 'bmp') {
            return (string) $image->toBitmap();
        }

        return (string) $image->encode();
    }

    return (string) $image->encode();
}
```

--------------------------------

### Register PHPStan extension manually in phpstan.neon

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Add this include to your phpstan.neon or phpstan.neon.dist file when you do not use phpstan/extension-installer. This registers the package's PHPStan extension to declare the runtime-registered Laravel macro methods.

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

--------------------------------

### FileUpload::macro('optimize') registration

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Registers the optimize macro on FileUpload, storing format and quality in imageOptimization and calling ensureOptimizerHook.

```php
FileUpload::macro('optimize', function (string | Closure | null $format = 'webp', int | Closure | null $quality = null) {
    $this->imageOptimization = $this->imageOptimization ?? [];
    $this->imageOptimization['format'] = $format;
    $this->imageOptimization['quality'] = $quality;
    $this->ensureOptimizerHook();

    return $this;
});
```

--------------------------------

### processAndStoreSpatie

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-processing.md

Optimizes a Livewire temporary uploaded file and stores it in the record's Spatie Media Library, returning the media UUID. This macro is registered on the FileUpload component and can be called directly on Livewire file upload components.

```APIDOC
## processAndStoreSpatie

### Description
Optimizes a Livewire temporary uploaded file and stores it in the record's Spatie Media Library, returning the media UUID. This macro is registered on the FileUpload component and can be called directly on Livewire file upload components.

### Method
MACRO

### Endpoint
FileUpload::processAndStoreSpatie($file, $record)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **$file** (TemporaryUploadedFile) - Required - Livewire temporary uploaded file.
- **$record** (?Illuminate\Database\Eloquent\Model) - Required - The Eloquent model receiving the media; `null` (or a model without `addMedia`) short-circuits with `null`.

### Request Example
```php
$uuid = $component->processAndStoreSpatie($file, $record);
```

### Response
#### Success Response (200)
- **string|null** - The `uuid` attribute of the created `Media` model, or `null` when `$record` is missing/doesn't have `addMedia()`.

#### Response Example
```php
'abc-123-def-456'
```

### Error Handling
- Returns `null` if `$record` is null or does not have `addMedia` method.
- Temp file is always removed in a `finally` block.
```

--------------------------------

### FileUpload::customHeaders()

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/overview.md

Runtime macro registered on Filament's FileUpload component (Spatie). It sets custom headers.

```APIDOC
## FileUpload::customHeaders()

### Description
Runtime macro registered on Filament's FileUpload component (Spatie). It sets custom headers.

### Method
customHeaders()

### Parameters
No parameters documented.

### Response
Returns $this for fluent chaining.
```

--------------------------------

### isSpatieComponent macro registration

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-processing.md

Registers the `isSpatieComponent` macro on FileUpload. Returns `true` only when the Spatie Media Library component class exists and the current component is an instance of it.

```php
FileUpload::macro('isSpatieComponent', function () {
    return class_exists('\Filament\Forms\Components\SpatieMediaLibraryFileUpload') &&
           $this instanceof SpatieMediaLibraryFileUpload;
});
```

--------------------------------

### maxImageWidth macro registration

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Registers the maxImageWidth macro on FileUpload, storing the width in imageOptimization and ensuring the optimizer hook.

```php
FileUpload::macro('maxImageWidth', function (int | Closure | null $width) {
    $this->imageOptimization = $this->imageOptimization ?? [];
    $this->imageOptimization['max_width'] = $width;
    $this->ensureOptimizerHook();

    return $this;
});
```

--------------------------------

### FileUpload::optimize()

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/overview.md

Runtime macro registered on Filament's FileUpload component. It is used to optimize an uploaded image.

```APIDOC
## FileUpload::optimize()

### Description
Runtime macro registered on Filament's FileUpload component. It is used to optimize an uploaded image.

### Method
optimize()

### Parameters
No parameters documented.

### Response
Returns $this for fluent chaining.
```

--------------------------------

### processV2 method (intervention/image v2)

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-processor.md

Protected static method that processes an image source using the intervention/image v2 API. Converts TemporaryUploadedFile sources to their real path, optionally resizes based on max dimensions or a percentage, and encodes the image. When $resize is set, it overwrites the max-derived dimension on the dominant axis. Encoding uses encode($format, $quality) if a format is given, otherwise encode() with original format and library default quality.

```php
protected static function processV2($source, $format, $resize, $maxWidth, $maxHeight, $quality): string
{
    if ($source instanceof TemporaryUploadedFile) {
        $source = $source->getRealPath();
    }

    $image = ImageManagerStatic::make($source);

    $shouldResize = false;
    $imageWidth = null;
    $imageHeight = null;

    if ($maxWidth && $image->width() > $maxWidth) {
        $shouldResize = true;
        $imageWidth = $maxWidth;
    }

    if ($maxHeight && $image->height() > $maxHeight) {
        $shouldResize = true;
        $imageHeight = $maxHeight;
    }

    if ($resize) {
        $shouldResize = true;
        if ($image->height() > $image->width()) {
            $imageHeight = $image->height() - ($image->height() * ($resize / 100));
        } else {
            $imageWidth = $image->width() - ($image->width() * ($resize / 100));
        }
    }

    if ($shouldResize) {
        $image->resize($imageWidth, $imageHeight, function ($constraint) {
            $constraint->aspectRatio();
        });
    }

    if ($format) {
        return (string) $image->encode($format, $quality);
    }

    return (string) $image->encode();
}
```

--------------------------------

### mediaName

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Sets the Media Library item name for Spatie-specific file uploads. This name is used when storing the media and falls back to the original filename if not set.

```APIDOC
## mediaName

### Description
Sets the Media Library item name for Spatie-specific file uploads. This name is used when storing the media and falls back to the original filename if not set.

### Method
Macro

### Parameters
- **$name** (string|Closure|null) - Required - Name passed to `$mediaAdder->usingName(...)`. When `null`/unset, `processAndStoreSpatie` falls back to `pathinfo($file->getClientOriginalName(), PATHINFO_FILENAME)` (the client's original filename without extension).

### Return
`$this` (FileUpload) - fluent.

### Example
```php
SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
    ->optimize('webp')
    ->mediaName('profile-picture');
```
```

--------------------------------

### customHeaders

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Spatie-specific macro that passes custom headers to Media Library's file-add operation (e.g., for S3 uploads). It is consumed only by processAndStoreSpatie and returns the FileUpload instance for fluent chaining.

```APIDOC
## customHeaders

### Description
Spatie-specific macro that passes custom headers to Media Library's file-add operation (e.g., for S3 uploads). It is consumed only by processAndStoreSpatie and returns the FileUpload instance for fluent chaining.

### Method
MACRO

### Endpoint
FileUpload::customHeaders()

### Parameters
#### Method Parameters
- **$headers** (array<mixed>|Closure|null) - Required - Associative array passed to `$mediaAdder->addCustomHeaders(...)`.

### Request Example
```php
SpatieMediaLibraryFileUpload::make('attachment')
    ->image()
    ->optimize('webp')
    ->customHeaders([
        'CacheControl' => 'max-age=604800',
    ]);
```

### Response
#### Success Response
- **$this** (FileUpload) - Fluent return for chaining.

#### Response Example
```php
FileUpload instance
```
```

--------------------------------

### FileUpload::maxImageHeight()

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/overview.md

Runtime macro registered on Filament's FileUpload component. It sets the maximum image height.

```APIDOC
## FileUpload::maxImageHeight()

### Description
Runtime macro registered on Filament's FileUpload component. It sets the maximum image height.

### Method
maxImageHeight()

### Parameters
No parameters documented.

### Response
Returns $this for fluent chaining.
```

--------------------------------

### FileUpload::maxImageWidth()

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/overview.md

Runtime macro registered on Filament's FileUpload component. It sets the maximum image width.

```APIDOC
## FileUpload::maxImageWidth()

### Description
Runtime macro registered on Filament's FileUpload component. It sets the maximum image width.

### Method
maxImageWidth()

### Parameters
No parameters documented.

### Response
Returns $this for fluent chaining.
```

--------------------------------

### Apache WebP MIME Type

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Add WebP MIME type to .htaccess for Apache servers to preview WebP images correctly.

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

--------------------------------

### Nginx WebP MIME Type

Source: https://github.com/danihidayatx/image-optimizer/blob/main/README.md

Ensure mime.types includes WebP MIME type for Nginx servers.

```nginx
image/webp webp;
```

--------------------------------

### ImageProcessor class skeleton

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/image-processor.md

Defines the processing engine shared by all upload paths. Accepts arbitrary image binary content or a Livewire TemporaryUploadedFile plus a settings array, and returns the encoded image as a raw string. Dispatches between Intervention Image v2 and v3 APIs.

```php
class ImageProcessor
{
    public static function process($source, array $settings): string
    // protected static function processV2(...)
    // protected static function processV3(...)
}
```

--------------------------------

### FileUpload::storeUploadedFileToDisk()

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/overview.md

Runtime macro registered on Filament's FileUpload component. It stores an uploaded file to disk.

```APIDOC
## FileUpload::storeUploadedFileToDisk()

### Description
Runtime macro registered on Filament's FileUpload component. It stores an uploaded file to disk.

### Method
storeUploadedFileToDisk()

### Parameters
No parameters documented.

### Response
No response documented.
```

--------------------------------

### Macro registration in ImageOptimizerServiceProvider.php

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-processing.md

Registers the storeUploadedFileToDisk macro on FileUpload. Moves the file directly when shouldMoveFiles() is true and the disk matches; otherwise uses storePubliclyAs or storeAs based on visibility.

```php
FileUpload::macro('storeUploadedFileToDisk', function (TemporaryUploadedFile $file) {
    /** @var FileUpload $component */
    $component = $this;
    $storeMethod = $component->getVisibility() === 'public' ? 'storePubliclyAs' : 'storeAs';

    if (
        $component->shouldMoveFiles() &&
        method_exists($file, 'getDisk') &&
        $component->getDiskName() === $file->getDisk()
    ) {
        $newPath = trim($component->getDirectory() . '/' . $component->getUploadedFileNameForStorage($file), '/');
        $component->getDisk()->move($file->path(), $newPath);

        return $newPath;
    }

    return $file->{$storeMethod}(
        $component->getDirectory(),
        $component->getUploadedFileNameForStorage($file),
        $component->getDiskName()
    );
});
```

--------------------------------

### maxImageHeight

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-config.md

Sets the maximum height for image optimization. The image is only resized if its height exceeds the given value, preserving aspect ratio.

```APIDOC
## maxImageHeight

### Description
Sets the maximum height for image optimization. The image is only resized if its height exceeds the given value, preserving aspect ratio.

### Method
Macro

### Parameters
- **$height** (int|Closure|null) - Required - Maximum height in pixels. Only applied when the source image's height exceeds this value. Aspect ratio is preserved.

### Return
`$this` (FileUpload) - fluent.

### Example
```php
FileUpload::make('attachment')
    ->image()
    ->maxImageHeight(768);
```
```

--------------------------------

### ensureOptimizerHook @method stub declaration

Source: https://github.com/danihidayatx/image-optimizer/blob/main/_autodocs/api-reference/file-upload-macros-processing.md

Stub declaration for the ensureOptimizerHook macro, copied from stubs/FileUpload.stub.php. The @method annotation is only accurate for the re-entry case; the actual closure returns null on first call.

```php
/**
 * @method $this ensureOptimizerHook()
 */
```
Tokens:
Raw