Image manipulation

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 and supports both PHP’s GD and Imagick extensions.

use Illuminate\Support\Facades\Image;

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

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.

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.

Installation

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

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.

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.

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.

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.

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.

$file = $image->file();

Storage files

Use the fromStorage method to create an image instance from a file stored on a filesystem disk. The first argument is the file path and the second argument is the disk name.

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.

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.

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.

$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

$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

$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.

$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.

$image = $image->toWebp();
$image = $image->toJpg();
$image = $image->toJpeg();

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

$image = $image->toWebp()->quality(80);

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

$image = $image->optimize();
$image = $image->optimize(format: 'jpg', quality: 85);

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

$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.

$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.

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

Use storePublicly and storePubliclyAs when storing with public visibility.

$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.

$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

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;
    }
}

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.

$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

namespace App\Images\Transformations;

use Illuminate\Contracts\Image\Transformation;

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

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.

use App\Images\Transformations\Pixelate;

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

Architecture

Database

Eloquent

Security

Events

Mail and Notifications

Payments

Asynchronous Processing

Real-time Communication

Scheduling

Cache and Optimization

Internationalization

Files and Storage

Debugging and Monitoring

Console and CLI

Performance

Frontend

AI Development

Development Environment

Introduction

Installation

Configuration

Loading images

Uploaded files

Storage files

Other sources

Manipulating images

Resizing

Other transformations

Conditional transformations

Encoding

Storing images

Retrieving image information

Custom drivers

Custom transformations

​Introduction

​Installation

​Configuration

​Loading images

​Uploaded files

​Storage files

​Other sources

​Manipulating images

​Resizing

​Other transformations

​Conditional transformations

​Encoding

​Storing images

​Retrieving image information

​Custom drivers

​Custom transformations

Introduction

Installation

Configuration

Loading images

Uploaded files

Storage files

Other sources

Manipulating images

Resizing

Other transformations

Conditional transformations

Encoding

Storing images

Retrieving image information

Custom drivers

Custom transformations