Procesamiento de imágenes

Explica cómo redimensionar, recortar, convertir y guardar imágenes usando la fachada Image de Laravel.

​

Introducción

Laravel ofrece una API fluida de procesamiento de imágenes a través de la fachada Image. Puedes describir operaciones como redimensionar, recortar, codificar o guardar con una notación coherente en todo el framework.

Internamente utiliza Intervention Image, que soporta tanto la extensión GD como la extensión Imagick de PHP.

use Illuminate\Support\Facades\Image;

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

El procesamiento de imágenes puede consumir mucha CPU y memoria. No proceses imágenes grandes dentro de una petición HTTP; considera hacerlo mediante un job de cola.

Esta funcionalidad está disponible desde Laravel v13.20.0. Si utilizas una versión anterior, actualiza el framework a la última con composer update.

​

Instalación

Antes de usar el procesamiento de imágenes, instala el paquete Intervention Image con Composer.

composer require intervention/image:^4.0

Además, verifica que tienes instalada la extensión GD o Imagick de PHP según el driver que vayas a utilizar.

​

Configuración

El archivo de configuración se ubica en config/image.php. Si no existe, publícalo con el comando Artisan.

php artisan config:publish image

El driver por defecto se puede indicar en el archivo de configuración o con la variable de entorno IMAGE_DRIVER. Los drivers soportados son gd e imagick.

IMAGE_DRIVER=imagick

​

Cargar imágenes

La fachada Image ofrece métodos para crear una instancia de imagen desde diversas fuentes. El contenido de la imagen se carga de forma perezosa, así que no se lee realmente hasta que se solicita el procesamiento o los bytes.

​

Archivo subido

Para obtener una imagen enviada desde una petición, usa el método image. Si el archivo no existe, devuelve 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');

    // ...
});

Para crearla a partir de una instancia de UploadedFile, usa fromUpload.

use Illuminate\Support\Facades\Image;

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

Para instancias creadas desde una subida, el método file te permite recuperar el archivo original.

$file = $image->file();

​

Archivo del storage

Para crear una instancia a partir de un archivo guardado en un disco del sistema de archivos, usa fromStorage. El primer argumento es la ruta y el segundo, el nombre del disco.

use Illuminate\Support\Facades\Image;

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

También puedes crearla desde el método image de la fachada Storage.

use Illuminate\Support\Facades\Storage;

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

​

Otras fuentes

También puedes crear una instancia a partir de bytes, una ruta local, una 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');

​

Procesar la imagen

Las instancias de imagen son inmutables. Cada método devuelve una nueva instancia con la transformación añadida al pipeline de procesamiento, así que puedes encadenarlas. Las transformaciones se aplican en el orden en que se añaden al pipeline y la codificación se realiza una sola vez al final.

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

​

Redimensionado

Método	Descripción
resize(800, 600)	Redimensiona al tamaño indicado. Se puede indicar solo el ancho o solo el alto
scale(800, 600)	Reduce manteniendo la proporción hasta caber en las dimensiones indicadas. No amplía
cover(400, 400)	Redimensiona y recorta para cubrir por completo las dimensiones indicadas
contain(400, 400)	Redimensiona manteniendo la proporción hasta caber en las dimensiones indicadas. Los márgenes se rellenan con el color de fondo
crop(300, 200)	Recorta al tamaño indicado. Se pueden indicar las coordenadas x e y

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

​

Otras transformaciones

$image = $image->orient();            // Rota según la orientación EXIF
$image = $image->rotate(90);          // Rota 90° en sentido horario
$image = $image->rotate(90, '#ffffff'); // Rota con color de fondo
$image = $image->blur(5);             // Desenfoque (0–100)
$image = $image->grayscale();         // Escala de grises
$image = $image->sharpen(10);         // Enfoque (0–100)
$image = $image->flipVertically();    // Voltear verticalmente
$image = $image->flipHorizontally();  // Voltear horizontalmente

​

Transformaciones condicionales

Las instancias de imagen soportan el trait Conditionable, que permite transformaciones condicionales 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());

​

Codificación

Por defecto se codifica en el formato original. Para cambiar de formato:

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

Con el método quality puedes fijar la calidad de salida (1–100).

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

optimize es un atajo para el cambio de formato y el ajuste de calidad. Por defecto usa WebP con calidad 70.

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

También puedes obtener los bytes, Base64 o data URI.

$bytes   = $image->toBytes();
$base64  = $image->toBase64();
$dataUri = $image->toDataUri();
$bytes   = (string) $image; // Casteo a cadena

​

Guardar

Con el método store guardas la imagen en un disco del sistema de archivos. Laravel genera automáticamente un nombre único y devuelve la ruta de guardado.

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

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

Para especificar el nombre de archivo, usa storeAs.

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

Para guardar con visibilidad 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');

Si falla el guardado, se devuelve false.

​

Obtener información de la imagen

Con los métodos mimeType, extension, dimensions, width y height puedes consultar la información de la imagen. Estos métodos operan sobre la imagen ya procesada (por ejemplo, tras cover(400, 400), llamar a width() devuelve 400).

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

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

​

Drivers personalizados

El gestor de imágenes de Laravel extiende Illuminate\Support\Manager, así que puedes registrar drivers personalizados con el método extend.

Un driver personalizado implementa la interfaz Illuminate\Contracts\Image\Driver, y en el método process recibe los bytes originales y el pipeline y devuelve los bytes procesados.

<?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
    {
        // Aplica las transformaciones y opciones de salida del pipeline...
        return $contents;
    }

    public function transformUsing(string $transformation, callable $callback): static
    {
        // Guarda el handler para poder aplicarlo durante el procesamiento...
        return $this;
    }
}

Regístralo en el método boot de 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;
    });
}

Para especificar el driver para una imagen concreta, usa using.

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

​

Transformaciones personalizadas

Puedes definir transformaciones personalizadas con una clase que implemente la interfaz 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,
    ) {}
}

Registra el handler en el método boot de 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);
});

Una vez registrado, aplícalo con transform.

use App\Images\Transformations\Pixelate;

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