Afbeeldingen bewerken

Introductie

Laravel biedt via de Image-facade een fluente API voor het bewerken van afbeeldingen. Bewerkingen zoals verkleinen, bijsnijden, encoderen en opslaan schrijf je op een manier die consistent is met de rest van het framework. Intern wordt Intervention Image gebruikt, met ondersteuning voor zowel de GD- als de Imagick-extensie van PHP.

use Illuminate\Support\Facades\Image;

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

Beeldverwerking kan veel CPU en geheugen verbruiken. Voer grootschalige beeldverwerking niet uit tijdens een HTTP-request, maar overweeg om die als queue-job te verwerken.

Deze functionaliteit is beschikbaar vanaf Laravel v13.20.0. Gebruik je een oudere versie, werk het framework dan bij naar de nieuwste versie met composer update.

Installatie

Installeer vóór het gebruik van de beeldbewerkingsfunctionaliteit het Intervention Image-pakket via Composer.

composer require intervention/image:^4.0

Controleer daarnaast dat, afhankelijk van de gebruikte driver, de GD- of Imagick-extensie van PHP is geïnstalleerd.

Configuratie

Het configuratiebestand bevindt zich in config/image.php. Bestaat het configuratiebestand niet, publiceer het dan met een Artisan-commando.

php artisan config:publish image

De standaarddriver stel je in via het configuratiebestand of de omgevingsvariabele IMAGE_DRIVER. De ondersteunde drivers zijn gd en imagick.

IMAGE_DRIVER=imagick

Afbeeldingen laden

De Image-facade biedt methoden om afbeeldingsinstanties uit diverse bronnen te maken. De inhoud van de afbeelding wordt lazy geladen; het daadwerkelijke laden gebeurt pas wanneer er verwerking of bytes worden opgevraagd.

Geüploade bestanden

Om een geüploade afbeelding uit het request op te halen, gebruik je de methode image. Bestaat het bestand niet, dan wordt null teruggegeven.

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

    // ...
});

Wil je een instantie maken van een UploadedFile-instantie, gebruik dan de methode fromUpload.

use Illuminate\Support\Facades\Image;

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

Bij een afbeeldingsinstantie die van een geüpload bestand is gemaakt, haal je met de methode file het oorspronkelijke bestand op.

$file = $image->file();

Bestanden uit storage

Om een afbeeldingsinstantie te maken van een bestand dat op een bestandssysteemdisk is opgeslagen, gebruik je de methode fromStorage. Het eerste argument is het bestandspad, het tweede de disknaam.

use Illuminate\Support\Facades\Image;

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

Je kunt er ook een maken via de methode image van de Storage-facade.

use Illuminate\Support\Facades\Storage;

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

Overige bronnen

Je kunt ook afbeeldingsinstanties maken van bytes, een lokaal pad, een URL of 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');

Afbeeldingsinstanties zijn immutable. Elke methode geeft een nieuwe instantie terug waarbij de transformatie is toegevoegd aan de verwerkingspipeline, zodat je alles als methodchain kunt schrijven. Transformaties worden verwerkt in de volgorde waarin ze aan de pipeline zijn toegevoegd; het encoderen gebeurt aan het eind slechts één keer.

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

Verkleinen

Methode	Beschrijving
`resize(800, 600)`	Verkleint naar het opgegeven formaat. Ook alleen breedte of hoogte is mogelijk
`scale(800, 600)`	Verkleint met behoud van verhouding zodat het binnen het opgegeven formaat past. Vergroot niet
`cover(400, 400)`	Verkleint en snijdt bij zodat het opgegeven formaat volledig wordt bedekt
`contain(400, 400)`	Verkleint met behoud van verhouding zodat het binnen het opgegeven formaat past. De marge wordt gevuld met de achtergrondkleur
`crop(300, 200)`	Snijdt bij op het opgegeven formaat. Ook `x`- en `y`-coördinaten zijn mogelijk

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

Overige transformaties

$image = $image->orient();            // Roteren volgens de EXIF-oriëntatie
$image = $image->rotate(90);          // 90° met de klok mee roteren
$image = $image->rotate(90, '#ffffff'); // Roteren met opgegeven achtergrondkleur
$image = $image->blur(5);             // Vervagen (0-100)
$image = $image->grayscale();         // Grijstinten
$image = $image->sharpen(10);         // Verscherpen (0-100)
$image = $image->flipVertically();    // Verticaal spiegelen
$image = $image->flipHorizontally();  // Horizontaal spiegelen

Voorwaardelijke transformaties

Afbeeldingsinstanties ondersteunen de Conditionable-trait, zodat je met when / unless voorwaardelijke transformaties kunt uitvoeren.

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

Encoderen

Standaard wordt geëncodeerd in het oorspronkelijke formaat. Om het formaat te converteren gebruik je de volgende methoden.

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

Met de methode quality stel je de uitvoerkwaliteit (1-100) in.

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

De methode optimize is een shortcut voor formaatconversie plus kwaliteitsinstelling. De standaard is WebP met kwaliteit 70.

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

Je kunt het resultaat ook ophalen als bytes, Base64 of Data URI.

$bytes   = $image->toBytes();
$base64  = $image->toBase64();
$dataUri = $image->toDataUri();
$dataUri = (string) $image; // Cast naar string

Opslaan

Met de methode store sla je de afbeelding op op een bestandssysteemdisk. Laravel genereert automatisch een unieke bestandsnaam en geeft het opslagpad terug.

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

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

Wil je zelf een bestandsnaam opgeven, gebruik dan storeAs.

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

Om op te slaan met public-zichtbaarheid gebruik je 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');

Mislukt het opslaan, dan wordt false teruggegeven.

Afbeeldingsinformatie ophalen

Met de methoden mimeType, extension, dimensions, width en height haal je informatie over de afbeelding op. Deze methoden hebben betrekking op de afbeelding ná verwerking (roep je bijvoorbeeld width() aan na cover(400, 400), dan krijg je 400 terug).

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

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

Aangepaste drivers

De imagemanager van Laravel erft over van Illuminate\Support\Manager en laat je met de methode extend aangepaste drivers registreren. Een aangepaste driver implementeert de interface Illuminate\Contracts\Image\Driver; de methode process ontvangt de oorspronkelijke afbeeldingsbytes en de pipeline en geeft de verwerkte afbeeldingsbytes terug.

<?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
    {
        // De transformaties en uitvoeropties van de pipeline toepassen...
        return $contents;
    }

    public function transformUsing(string $transformation, callable $callback): static
    {
        // De handler opslaan zodat hij tijdens de verwerking kan worden toegepast...
        return $this;
    }
}

De registratie doe je in de boot-methode van een serviceprovider.

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

Om voor een specifieke afbeelding een driver op te geven gebruik je de methode using.

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

Aangepaste transformaties

Je definieert aangepaste transformaties met een klasse die de interface Illuminate\Contracts\Image\Transformation implementeert.

<?php

namespace App\Images\Transformations;

use Illuminate\Contracts\Image\Transformation;

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

De handler registreer je in de boot-methode van een serviceprovider.

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

Na registratie pas je de transformatie toe met de methode transform.

use App\Images\Transformations\Pixelate;

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

Architectuur

Database

Eloquent

Beveiliging

Events

E-mail en notificaties

Betalingen

Asynchrone verwerking

Realtime communicatie

Taakplanning

Caching en optimalisatie

Internationalisatie

Bestanden en opslag

Debugging en monitoring

Console en CLI

Performance

Frontend

AI-ontwikkeling

Ontwikkelomgeving