Traitement d'images

Introduction

Laravel expose, via la façade Image, une API fluide de traitement d’images. Le redimensionnement, le recadrage, l’encodage ou la sauvegarde s’écrivent de manière homogène sur l’ensemble du framework. En interne, la façade s’appuie sur Intervention Image et prend en charge à la fois les extensions PHP GD et Imagick.

use Illuminate\Support\Facades\Image;

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

Le traitement d’images peut être très gourmand en CPU et en mémoire. Pour des opérations lourdes, évitez de les exécuter pendant une requête HTTP et déléguez-les à un job de queue.

Cette fonctionnalité est disponible à partir de Laravel v13.20.0. Si vous utilisez une version plus ancienne, mettez le framework à jour avec composer update.

Installation

Avant d’utiliser le traitement d’images, installez le package Intervention Image via Composer.

composer require intervention/image:^4.0

Vérifiez également que l’extension PHP GD ou Imagick est installée selon le driver que vous souhaitez utiliser.

Configuration

Le fichier de configuration est config/image.php. S’il n’existe pas, publiez-le via la commande Artisan.

php artisan config:publish image

Le driver par défaut peut être défini dans le fichier de configuration ou via la variable d’environnement IMAGE_DRIVER. Les drivers pris en charge sont gd et imagick.

IMAGE_DRIVER=imagick

Charger une image

La façade Image propose plusieurs méthodes pour créer une instance d’image depuis diverses sources. Le contenu de l’image est chargé de façon paresseuse : il n’est effectivement lu qu’au moment du traitement ou de la demande des octets.

Fichier téléversé

Pour récupérer une image téléversée depuis la requête, utilisez la méthode image. Si le fichier est absent, null est renvoyé.

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');

    // ...
});

Pour créer l’instance depuis un UploadedFile, utilisez fromUpload.

use Illuminate\Support\Facades\Image;

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

Depuis une instance créée à partir d’un fichier téléversé, la méthode file permet de récupérer le fichier d’origine.

$file = $image->file();

Fichier du stockage

Pour créer une instance à partir d’un fichier situé sur un disque de système de fichiers, utilisez fromStorage. Le premier argument est le chemin, le second le nom du disque.

use Illuminate\Support\Facades\Image;

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

La façade Storage propose également une méthode image.

use Illuminate\Support\Facades\Storage;

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

Autres sources

Vous pouvez aussi partir d’octets, d’un chemin local, d’une URL ou d’une chaîne Base64.

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');

Transformer une image

Les instances d’image sont immuables. Chaque méthode renvoie une nouvelle instance dans laquelle la transformation a été ajoutée au pipeline de traitement, ce qui permet le chaînage. Les transformations sont appliquées dans l’ordre d’ajout, et l’encodage n’est effectué qu’à la toute fin.

$image = $request->image('avatar')
    ->orient()
    ->cover(400, 400)
    ->sharpen(10);

Redimensionnement

Méthode	Description
`resize(800, 600)`	Redimensionne à la taille indiquée. Vous pouvez ne fournir que la largeur ou la hauteur.
`scale(800, 600)`	Réduit en conservant les proportions pour tenir dans la taille indiquée. N’agrandit pas.
`cover(400, 400)`	Redimensionne et recadre pour couvrir intégralement la taille indiquée.
`contain(400, 400)`	Redimensionne en gardant les proportions pour tenir dans la taille indiquée. Complète avec une couleur de fond.
`crop(300, 200)`	Recadre à la taille indiquée. Les coordonnées `x` / `y` sont facultatives.

$image = $image->resize(800, 600);
$image = $image->resize(width: 800);       // largeur uniquement
$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);

Autres transformations

$image = $image->orient();             // Applique l'orientation selon les données EXIF
$image = $image->rotate(90);           // Rotation de 90° dans le sens horaire
$image = $image->rotate(90, '#ffffff'); // Rotation avec couleur d'arrière-plan
$image = $image->blur(5);              // Flou (0 à 100)
$image = $image->grayscale();          // Niveaux de gris
$image = $image->sharpen(10);          // Netteté (0 à 100)
$image = $image->flipVertically();     // Miroir vertical
$image = $image->flipHorizontally();   // Miroir horizontal

Transformations conditionnelles

Les instances d’image supportent le trait Conditionable : when / unless permettent d’appliquer des transformations sous condition.

$image = $request->image('avatar')
    ->when($request->boolean('crop'), fn ($image) => $image->cover(400, 400))
    ->unless($request->boolean('preserve_format'), fn ($image) => $image->toWebp());

Encodage

Par défaut, l’encodage utilise le format d’origine. Pour convertir vers un autre format, utilisez :

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

La méthode quality fixe la qualité de sortie (1 à 100).

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

optimize est un raccourci pour convertir le format et définir la qualité. Par défaut : WebP, qualité 70.

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

Vous pouvez également obtenir des octets bruts, du Base64 ou une Data URI.

$bytes   = $image->toBytes();
$base64  = $image->toBase64();
$dataUri = $image->toDataUri();
$bytes   = (string) $image; // Cast en chaîne de caractères

Enregistrer une image

La méthode store sauvegarde l’image sur un disque de fichiers. Laravel génère un nom unique et renvoie le chemin où l’image a été enregistrée.

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

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

Pour préciser le nom de fichier, utilisez storeAs.

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

Pour une visibilité public, utilisez storePublicly / storePubliclyAs.

$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');

En cas d’échec, false est renvoyé.

Obtenir des informations sur l’image

Les méthodes mimeType, extension, dimensions, width et height renvoient des informations sur l’image telle qu’elle sera après traitement (par exemple, après cover(400, 400), width() renvoie 400).

$mimeType = $image->mimeType();
$extension = $image->extension();

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

Drivers personnalisés

Le gestionnaire d’images de Laravel hérite de Illuminate\Support\Manager : la méthode extend permet d’enregistrer un driver personnalisé. Le driver doit implémenter l’interface Illuminate\Contracts\Image\Driver. Sa méthode process reçoit les octets d’origine et le pipeline, et renvoie les octets de l’image traitée.

<?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
    {
        // Appliquer les transformations et options de sortie du pipeline...
        return $contents;
    }

    public function transformUsing(string $transformation, callable $callback): static
    {
        // Enregistrer le handler pour l'appliquer pendant le traitement...
        return $this;
    }
}

L’enregistrement se fait dans la méthode boot d’un service provider.

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

Pour indiquer un driver sur une image particulière, utilisez using.

$image = $request->image('avatar')
    ->using('vips')
    ->cover(400, 400);

Transformations personnalisées

Vous pouvez définir une transformation personnalisée en implémentant l’interface Illuminate\Contracts\Image\Transformation.

<?php

namespace App\Images\Transformations;

use Illuminate\Contracts\Image\Transformation;

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

Enregistrez son handler dans la méthode boot d’un service provider.

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

Une fois enregistrée, appliquez-la via transform.

use App\Images\Transformations\Pixelate;

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

Architecture

Base de données

Eloquent

Sécurité

Événements

E-mails et notifications

Paiements

Traitement asynchrone

Communication temps réel

Planification

Cache et optimisation

Internationalisation

Fichiers et stockage

Débogage et supervision

Console et CLI

Performance

Frontend

Développement IA

Environnement de développement

Introduction

Installation

Configuration

Charger une image

Fichier téléversé

Fichier du stockage

Autres sources

Transformer une image

Redimensionnement

Autres transformations

Transformations conditionnelles

Encodage

Enregistrer une image

Obtenir des informations sur l’image

Drivers personnalisés

Transformations personnalisées

​Introduction

​Installation

​Configuration

​Charger une image

​Fichier téléversé

​Fichier du stockage

​Autres sources

​Transformer une image

​Redimensionnement

​Autres transformations

​Transformations conditionnelles

​Encodage

​Enregistrer une image

​Obtenir des informations sur l’image

​Drivers personnalisés

​Transformations personnalisées

Introduction

Installation

Configuration

Charger une image

Fichier téléversé

Fichier du stockage

Autres sources

Transformer une image

Redimensionnement

Autres transformations

Transformations conditionnelles

Encodage

Enregistrer une image

Obtenir des informations sur l’image

Drivers personnalisés

Transformations personnalisées