> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Image manipulation

> Learn how to resize, crop, convert, and store images using Laravel's Image facade.

## Introduction

Laravel provides a fluent image manipulation API through the `Image` facade. You can express operations such as resizing, cropping, encoding, and storing images in a consistent way across the framework.

Internally, it uses [Intervention Image](https://image.intervention.io/) and supports both PHP's GD and Imagick extensions.

```php theme={null}
use Illuminate\Support\Facades\Image;

$path = Image::fromStorage('avatars/photo.jpg', 'public')
    ->cover(400, 400)
    ->toWebp()
    ->quality(80)
    ->storePublicly('avatars', 'public');
```

<Warning>
  Image processing can consume significant CPU and memory. For large-scale image processing, avoid doing the work during an HTTP request and consider processing images as [queue jobs](/en/queues).
</Warning>

<Info>
  This feature is available in **Laravel v13.20.0 and later**. If you are using an older version, update the framework to the latest release with `composer update`.
</Info>

## Installation

Before using image manipulation features, install the Intervention Image package with Composer.

```shell theme={null}
composer require intervention/image:^4.0
```

Also make sure the PHP GD extension or Imagick extension is installed, depending on the driver you want to use.

### Configuration

The configuration file is placed at `config/image.php`. If it does not exist, publish it with an Artisan command.

```shell theme={null}
php artisan config:publish image
```

You can specify the default driver in the config file or with the `IMAGE_DRIVER` environment variable. Supported drivers are `gd` and `imagick`.

```ini theme={null}
IMAGE_DRIVER=imagick
```

## Loading images

The `Image` facade provides methods for creating image instances from several sources. Image contents are loaded lazily, so the underlying bytes are not read until processing or output is requested.

### Uploaded files

Use the `image` method to retrieve an uploaded image from the request. It returns `null` when the file is not present.

```php theme={null}
use Illuminate\Http\Request;

Route::post('/avatar', function (Request $request) {
    $request->validate(['avatar' => ['required', 'image']]);

    $path = $request->image('avatar')
        ->cover(400, 400)
        ->toWebp()
        ->storePublicly('avatars', 'public');

    // ...
});
```

Use the `fromUpload` method when creating an image from an `UploadedFile` instance.

```php theme={null}
use Illuminate\Support\Facades\Image;

$image = Image::fromUpload($request->file('avatar'));
```

You can retrieve the original file from an image instance created from an uploaded file with the `file` method.

```php theme={null}
$file = $image->file();
```

### Storage files

Use the `fromStorage` method to create an image instance from a file stored on a [filesystem disk](/en/filesystem). The first argument is the file path and the second argument is the disk name.

```php theme={null}
use Illuminate\Support\Facades\Image;

$image = Image::fromStorage('avatars/photo.jpg', disk: 'public');
```

You can also create an image through the Storage facade's `image` method.

```php theme={null}
use Illuminate\Support\Facades\Storage;

$image = Storage::disk('public')->image('avatars/photo.jpg');
```

### Other sources

You can also create image instances from bytes, local paths, URLs, and Base64 strings.

```php theme={null}
use Illuminate\Support\Facades\Image;

$image = Image::fromBytes($contents);
$image = Image::fromBase64($base64);
$image = Image::fromPath(storage_path('app/avatars/photo.jpg'));
$image = Image::fromUrl('https://example.com/photo.jpg');
```

## Manipulating images

Image instances are immutable. Each method returns a new instance with a transformation added to the processing pipeline, making method chaining natural. Transformations are applied in the order they are added, and encoding happens only once at the end.

```php theme={null}
$image = $request->image('avatar')
    ->orient()
    ->cover(400, 400)
    ->sharpen(10);
```

### Resizing

| Method              | Description                                                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `resize(800, 600)`  | Resize to the specified dimensions. Width-only or height-only resizing is also supported                                   |
| `scale(800, 600)`   | Scale down to fit within the specified dimensions while preserving aspect ratio. Does not upscale                          |
| `cover(400, 400)`   | Resize and crop so the image fully covers the specified dimensions                                                         |
| `contain(400, 400)` | Resize to fit within the specified dimensions while preserving aspect ratio. Empty space is filled with a background color |
| `crop(300, 200)`    | Crop to the specified dimensions. `x` and `y` coordinates can also be specified                                            |

```php theme={null}
$image = $image->resize(800, 600);
$image = $image->resize(width: 800);       // Width only
$image = $image->scale(800, 600);
$image = $image->cover(400, 400);
$image = $image->contain(400, 400, '#ffffff');
$image = $image->crop(300, 200, x: 50, y: 25);
```

### Other transformations

```php theme={null}
$image = $image->orient();              // Rotate according to EXIF orientation
$image = $image->rotate(90);            // Rotate 90 degrees clockwise
$image = $image->rotate(90, '#ffffff'); // Rotate with a background color
$image = $image->blur(5);               // Blur (0-100)
$image = $image->grayscale();           // Convert to grayscale
$image = $image->sharpen(10);           // Sharpen (0-100)
$image = $image->flipVertically();      // Flip vertically
$image = $image->flipHorizontally();    // Flip horizontally
```

### Conditional transformations

Image instances support the `Conditionable` trait, so you can apply transformations conditionally with `when` and `unless`.

```php theme={null}
$image = $request->image('avatar')
    ->when($request->boolean('crop'), fn ($image) => $image->cover(400, 400))
    ->unless($request->boolean('preserve_format'), fn ($image) => $image->toWebp());
```

## Encoding

By default, images are encoded in their original format. Use the following methods to convert formats.

```php theme={null}
$image = $image->toWebp();
$image = $image->toJpg();
$image = $image->toJpeg();
```

Use the `quality` method to set output quality from 1 to 100.

```php theme={null}
$image = $image->toWebp()->quality(80);
```

The `optimize` method is a shortcut for format conversion and quality configuration. The default is WebP at quality 70.

```php theme={null}
$image = $image->optimize();
$image = $image->optimize(format: 'jpg', quality: 85);
```

You can also retrieve the result as bytes, Base64, or a data URI.

```php theme={null}
$bytes   = $image->toBytes();
$base64  = $image->toBase64();
$dataUri = $image->toDataUri();
$bytes   = (string) $image; // String cast
```

## Storing images

Use the `store` method to store an image on a filesystem disk. Laravel automatically generates a unique filename and returns the stored path.

```php theme={null}
$path = $request->image('avatar')
    ->cover(400, 400)
    ->store(path: 'avatars');

$path = $request->image('avatar')
    ->cover(400, 400)
    ->store(path: 'avatars', disk: 's3');
```

Use `storeAs` when you want to specify the filename.

```php theme={null}
$path = $request->image('avatar')
    ->cover(400, 400)
    ->storeAs(path: 'avatars', name: 'avatar.jpg', disk: 'public');
```

Use `storePublicly` and `storePubliclyAs` when storing with `public` visibility.

```php theme={null}
$path = $request->image('avatar')
    ->cover(400, 400)
    ->storePublicly(path: 'avatars', disk: 'public');

$path = $request->image('avatar')
    ->cover(400, 400)
    ->storePubliclyAs(path: 'avatars', name: 'avatar.webp', disk: 'public');
```

If storing fails, these methods return `false`.

## Retrieving image information

Use the `mimeType`, `extension`, `dimensions`, `width`, and `height` methods to retrieve image information. These methods reflect the processed image. For example, calling `width()` after `cover(400, 400)` returns `400`.

```php theme={null}
$mimeType = $image->mimeType();
$extension = $image->extension();

[$width, $height] = $image->dimensions();
$width  = $image->width();
$height = $image->height();
```

## Custom drivers

Laravel's image manager extends `Illuminate\Support\Manager`, so you can register custom drivers with the `extend` method.

A custom driver implements the `Illuminate\Contracts\Image\Driver` interface. Its `process` method receives the original image bytes and the pipeline, then returns the processed image bytes.

```php theme={null}
<?php

namespace App\Images;

use Illuminate\Contracts\Image\Driver;
use Illuminate\Image\ImagePipeline;

class VipsDriver implements Driver
{
    public function process(string $contents, ImagePipeline $pipeline): string
    {
        // Apply the pipeline transformations and output options...
        return $contents;
    }

    public function transformUsing(string $transformation, callable $callback): static
    {
        // Store the handler so it can be applied during processing...
        return $this;
    }
}
```

Register the driver in a service provider's `boot` method.

```php theme={null}
use App\Images\VipsDriver;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Image;

public function boot(): void
{
    Image::extend('vips', function (Application $app) {
        return new VipsDriver;
    });
}
```

Use the `using` method to select a driver for a specific image.

```php theme={null}
$image = $request->image('avatar')
    ->using('vips')
    ->cover(400, 400);
```

## Custom transformations

Define custom transformations with classes that implement the `Illuminate\Contracts\Image\Transformation` interface.

```php theme={null}
<?php

namespace App\Images\Transformations;

use Illuminate\Contracts\Image\Transformation;

class Pixelate implements Transformation
{
    public function __construct(
        public readonly int $size,
    ) {}
}
```

Register the handler in a service provider's `boot` method.

```php theme={null}
use App\Images\Transformations\Pixelate;
use Illuminate\Support\Facades\Image;
use Intervention\Image\Interfaces\ImageInterface;

Image::transformUsing('gd', Pixelate::class, function (ImageInterface $image, Pixelate $transformation) {
    return $image->pixelate($transformation->size);
});
```

After registration, apply it with the `transform` method.

```php theme={null}
use App\Images\Transformations\Pixelate;

$image = $request->image('avatar')
    ->transform(new Pixelate(12))
    ->store('avatars');
```


## Related topics

- [URL generation](/en/urls.md)
- [Speaker Info](/en/packages/laravel-voicevox/engine-api/other/speaker-info.md)
- [Singer Info](/en/packages/laravel-voicevox/engine-api/other/singer-info.md)
- [Installed Libraries](/en/packages/laravel-voicevox/engine-api/voice-library-management/installed-libraries.md)
- [Downloadable Libraries](/en/packages/laravel-voicevox/engine-api/voice-library-management/downloadable-libraries.md)