Elaborazione immagini

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, supportando sia l’estensione PHP GD sia Imagick.

use Illuminate\Support\Facades\Image;

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

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.

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

Installazione

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

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.

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.

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.

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.

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.

$file = $image->file();

File dallo storage

Per creare un’immagine da un file su disco filesystem usa fromStorage. Il primo argomento è il path, il secondo il nome del disco.

use Illuminate\Support\Facades\Image;

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

Puoi anche partire dal metodo image della facade Storage.

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.

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.

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

$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

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

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

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

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

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

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

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

Puoi anche ottenere byte, Base64 o data URI.

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

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

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

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

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

$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

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.

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.

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

Trasformazioni personalizzate

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

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

Dopo la registrazione, applicala con transform.

use App\Images\Transformations\Pixelate;

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

Architettura

Database

Eloquent

Sicurezza

Eventi

Mail e notifiche

Pagamenti

Elaborazione asincrona

Comunicazione in tempo reale

Scheduling

Cache e ottimizzazione

Internazionalizzazione

File e storage

Debug e monitoraggio

Console e CLI

Performance

Frontend

Sviluppo con AI

Ambiente di sviluppo

Introduzione

Installazione

Configurazione

Caricare un’immagine

File caricati

File dallo storage

Altre sorgenti

Elaborare l’immagine

Resize

Altre trasformazioni

Trasformazioni condizionali

Encoding

Salvataggio

Ottenere informazioni sull’immagine

Driver personalizzati

Trasformazioni personalizzate

​Introduzione

​Installazione

​Configurazione

​Caricare un’immagine

​File caricati

​File dallo storage

​Altre sorgenti

​Elaborare l’immagine

​Resize

​Altre trasformazioni

​Trasformazioni condizionali

​Encoding

​Salvataggio

​Ottenere informazioni sull’immagine

​Driver personalizzati

​Trasformazioni personalizzate

Introduzione

Installazione

Configurazione

Caricare un’immagine

File caricati

File dallo storage

Altre sorgenti

Elaborare l’immagine

Resize

Altre trasformazioni

Trasformazioni condizionali

Encoding

Salvataggio

Ottenere informazioni sull’immagine

Driver personalizzati

Trasformazioni personalizzate