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

# Traitement d'images

> Découvrez comment redimensionner, recadrer, convertir et enregistrer des images via la façade Image de Laravel.

## 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](https://image.intervention.io/) et prend en charge à la fois les extensions PHP GD et Imagick.

```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>
  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](/fr/queues).
</Warning>

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

## Installation

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

```shell theme={null}
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.

```shell theme={null}
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`.

```ini theme={null}
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é.

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

    // ...
});
```

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

```php theme={null}
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.

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

### Fichier du stockage

Pour créer une instance à partir d'un fichier situé sur un [disque de système de fichiers](/fr/filesystem), utilisez `fromStorage`. Le premier argument est le chemin, le second le nom du disque.

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

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

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

```php theme={null}
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.

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

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

```php theme={null}
$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.                                      |

```php theme={null}
$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

```php theme={null}
$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.

```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());
```

## Encodage

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

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

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

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

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

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

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

```php theme={null}
$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.

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

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

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

Pour une visibilité `public`, utilisez `storePublicly` / `storePubliclyAs`.

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

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`).

```php theme={null}
$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 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
    {
        // 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.

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

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

```php theme={null}
$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 theme={null}
<?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.

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

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

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

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


## Related topics

- [Laravel AI SDK](/fr/ai-sdk.md)
- [Pilote Amazon Bedrock pour Laravel AI SDK](/fr/packages/laravel-amazon-bedrock.md)
- [Queues et jobs](/fr/queues.md)
- [Les nouveautés de Laravel 13](/fr/blog/laravel-13-new-features.md)
- [Créer un fournisseur personnalisé pour l'AI SDK](/fr/advanced/ai-sdk-custom-provider.md)