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

# Elaborazione immagini

> Come effettuare resize, crop, conversione e salvataggio di immagini con la facade Image di Laravel.

## Introduzione

Laravel offre, tramite la facade `Image`, un'API fluida per l'elaborazione delle immagini. Resize, crop, encoding e salvataggio possono essere descritti in modo uniforme in tutto il framework.

Internamente utilizza [Intervention Image](https://image.intervention.io/), supportando sia l'estensione PHP GD sia 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>
  L'elaborazione delle immagini può consumare molta CPU e memoria. Per elaborazioni pesanti, non farla durante la richiesta HTTP: valuta di usare [job in coda](/it/queues).
</Warning>

<Info>
  Questa funzionalità è disponibile da **Laravel v13.20.0 in poi**. Se usi una versione precedente, aggiorna il framework con `composer update`.
</Info>

## Installazione

Prima di usare l'elaborazione immagini, installa Intervention Image via Composer.

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

Verifica anche che sia installata l'estensione PHP GD o Imagick, in base al driver che intendi usare.

### Configurazione

Il file di configurazione si trova in `config/image.php`. Se non esiste, pubblicalo con il comando Artisan.

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

Il driver di default si imposta nel file di configurazione o con la variabile d'ambiente `IMAGE_DRIVER`. Sono supportati `gd` e `imagick`.

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

## Caricare un'immagine

La facade `Image` offre metodi per creare istanze di immagine da varie sorgenti. Il contenuto viene caricato in modo lazy: viene letto effettivamente solo quando serve elaborare l'immagine o produrre i byte.

### File caricati

Per ottenere un'immagine caricata dalla richiesta usa il metodo `image`. Se il file non c'è restituisce `null`.

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

    // ...
});
```

Per crearla da un'istanza `UploadedFile` usa `fromUpload`.

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

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

Sulle immagini create da upload, con il metodo `file` puoi recuperare il file originale.

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

### File dallo storage

Per creare un'immagine da un file su [disco filesystem](/it/filesystem) usa `fromStorage`. Il primo argomento è il path, il secondo il nome del disco.

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

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

Puoi anche partire dal metodo `image` della facade Storage.

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

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

### Altre sorgenti

Puoi creare un'immagine anche da byte, path locale, URL o 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');
```

## Elaborare l'immagine

Le istanze immagine sono immutabili. Ogni metodo restituisce una nuova istanza con la trasformazione aggiunta alla pipeline di elaborazione, così puoi concatenarli. Le trasformazioni vengono applicate nell'ordine in cui sono aggiunte alla pipeline e l'encoding avviene una sola volta alla fine.

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

### Resize

| Metodo              | Descrizione                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `resize(800, 600)`  | Ridimensiona alle dimensioni indicate. Puoi passare anche solo larghezza o altezza                                        |
| `scale(800, 600)`   | Riduce mantenendo le proporzioni per stare dentro le dimensioni. Non ingrandisce                                          |
| `cover(400, 400)`   | Ridimensiona e croppa per coprire completamente le dimensioni indicate                                                    |
| `contain(400, 400)` | Ridimensiona mantenendo le proporzioni per rientrare nella dimensione; i margini vengono riempiti con il colore di sfondo |
| `crop(300, 200)`    | Crop alla dimensione indicata. Puoi passare anche le coordinate `x` e `y`                                                 |

```php theme={null}
$image = $image->resize(800, 600);
$image = $image->resize(width: 800);       // solo larghezza
$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);
```

### Altre trasformazioni

```php theme={null}
$image = $image->orient();            // ruota in base all'orientamento EXIF
$image = $image->rotate(90);          // ruota di 90° in senso orario
$image = $image->rotate(90, '#ffffff'); // ruota con colore di sfondo
$image = $image->blur(5);             // sfocatura (0-100)
$image = $image->grayscale();         // scala di grigi
$image = $image->sharpen(10);         // sharpen (0-100)
$image = $image->flipVertically();    // capovolge verticalmente
$image = $image->flipHorizontally();  // capovolge orizzontalmente
```

### Trasformazioni condizionali

L'immagine supporta il trait `Conditionable`, quindi puoi applicare trasformazioni condizionali con `when` / `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

Per default l'encoding usa il formato originale. Per convertire formato usa questi metodi.

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

Con `quality` imposti la qualità di output (1-100).

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

`optimize` è una scorciatoia per conversione di formato e qualità. Il default è WebP con qualità 70.

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

Puoi anche ottenere byte, Base64 o data URI.

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

## Salvataggio

Con `store` salvi l'immagine su un disco filesystem. Laravel genera un nome file univoco e restituisce il path di salvataggio.

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

Per specificare il nome file usa `storeAs`.

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

Per salvare con visibilità `public` usa `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');
```

Se il salvataggio fallisce restituisce `false`.

## Ottenere informazioni sull'immagine

Con `mimeType`, `extension`, `dimensions`, `width`, `height` recuperi le informazioni. Si riferiscono all'immagine dopo l'elaborazione (ad esempio, dopo `cover(400, 400)`, `width()` restituisce `400`).

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

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

## Driver personalizzati

L'image manager di Laravel estende `Illuminate\Support\Manager`, quindi puoi registrare driver personalizzati con `extend`.

Un driver personalizzato implementa `Illuminate\Contracts\Image\Driver` e nel metodo `process` riceve i byte dell'immagine originale e la pipeline, restituendo i byte elaborati.

```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
    {
        // applica le trasformazioni della pipeline e le opzioni di output...
        return $contents;
    }

    public function transformUsing(string $transformation, callable $callback): static
    {
        // memorizza gli handler per poterli applicare durante l'elaborazione...
        return $this;
    }
}
```

La registrazione avviene nel metodo `boot` di 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;
    });
}
```

Per usare un driver specifico su una singola immagine chiama `using`.

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

## Trasformazioni personalizzate

Puoi definire trasformazioni personalizzate implementando `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,
    ) {}
}
```

L'handler si registra nel metodo `boot` del 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);
});
```

Dopo la registrazione, applicala con `transform`.

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

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


## Related topics

- [Code e job](/it/queues.md)
- [Laravel Sail](/it/sail.md)
- [Laravel AI SDK](/it/ai-sdk.md)
- [Driver Amazon Bedrock per Laravel AI SDK](/it/packages/laravel-amazon-bedrock.md)
- [Laravel Head — pacchetto per gestire il <head> del documento](/it/blog/laravel-head-introduction.md)