Bildbearbeitung

Einführung

Laravel stellt über die Image-Facade eine fluente API zur Bildbearbeitung bereit. Operationen wie Skalieren, Zuschneiden, Kodieren und Speichern lassen sich damit einheitlich innerhalb des Frameworks ausdrücken. Intern kommt Intervention Image zum Einsatz, das sowohl die PHP-Extension GD als auch Imagick unterstützt.

use Illuminate\Support\Facades\Image;

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

Bildverarbeitung kann sehr CPU- und speicherintensiv sein. Führen Sie umfangreiche Bildverarbeitung nicht während eines HTTP-Requests aus, sondern ziehen Sie eine Verarbeitung als Queue-Job in Betracht.

Diese Funktion steht ab Laravel v13.20.0 zur Verfügung. Wenn Sie eine ältere Version verwenden, aktualisieren Sie das Framework mit composer update auf die neueste Version.

Installation

Bevor Sie die Bildbearbeitungsfunktionen nutzen können, installieren Sie das Paket Intervention Image über Composer.

composer require intervention/image:^4.0

Stellen Sie außerdem sicher, dass die passende PHP-Extension (GD oder Imagick) für den gewünschten Treiber installiert ist.

Konfiguration

Die Konfigurationsdatei liegt unter config/image.php. Wenn sie noch nicht vorhanden ist, veröffentlichen Sie sie mit dem Artisan-Befehl.

php artisan config:publish image

Der Standardtreiber kann in der Konfigurationsdatei oder über die Umgebungsvariable IMAGE_DRIVER festgelegt werden. Unterstützte Treiber sind gd und imagick.

IMAGE_DRIVER=imagick

Bilder laden

Die Image-Facade bietet Methoden zum Erzeugen von Bildinstanzen aus verschiedenen Quellen. Der Inhalt eines Bildes wird verzögert geladen und daher erst dann tatsächlich gelesen, wenn eine Verarbeitung oder Bytes angefordert werden.

Hochgeladene Dateien

Um ein aus dem Request hochgeladenes Bild zu erhalten, verwenden Sie die Methode image. Falls die Datei nicht existiert, wird null zurückgegeben.

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

    // ...
});

Zum Erzeugen aus einer UploadedFile-Instanz verwenden Sie die Methode fromUpload.

use Illuminate\Support\Facades\Image;

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

Eine aus einer hochgeladenen Datei erzeugte Bildinstanz stellt über die Methode file die ursprüngliche Datei bereit.

$file = $image->file();

Dateien aus dem Storage

Um eine Bildinstanz aus einer auf einem Filesystem-Disk gespeicherten Datei zu erzeugen, verwenden Sie die Methode fromStorage. Das erste Argument ist der Dateipfad, das zweite der Disk-Name.

use Illuminate\Support\Facades\Image;

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

Sie können sie auch über die image-Methode der Storage-Facade erzeugen.

use Illuminate\Support\Facades\Storage;

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

Weitere Quellen

Bildinstanzen können auch aus Byte-Strings, lokalen Pfaden, URLs oder Base64 erzeugt werden.

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

Bildinstanzen sind unveränderlich (immutable). Jede Methode fügt eine Transformation zur Verarbeitungspipeline hinzu und liefert eine neue Instanz zurück, sodass sich Methoden verketten lassen. Transformationen werden in der Reihenfolge angewendet, in der sie der Pipeline hinzugefügt wurden; das Kodieren erfolgt am Ende genau einmal.

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

Skalieren

Methode	Beschreibung
`resize(800, 600)`	Skaliert auf die angegebene Größe. Es können auch nur Breite oder nur Höhe angegeben werden
`scale(800, 600)`	Verkleinert unter Wahrung des Seitenverhältnisses so, dass das Bild in die angegebene Größe passt. Es wird nicht vergrößert
`cover(400, 400)`	Skaliert und beschneidet, sodass die angegebene Größe vollständig abgedeckt wird
`contain(400, 400)`	Skaliert unter Wahrung des Seitenverhältnisses in die angegebene Größe hinein. Ränder werden mit der Hintergrundfarbe gefüllt
`crop(300, 200)`	Beschneidet auf die angegebene Größe. `x`- und `y`-Koordinaten sind ebenfalls angebbar

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

Weitere Transformationen

$image = $image->orient();            // Dreht gemäß den EXIF-Orientierungsinformationen
$image = $image->rotate(90);          // Dreht 90° im Uhrzeigersinn
$image = $image->rotate(90, '#ffffff'); // Rotieren mit angegebener Hintergrundfarbe
$image = $image->blur(5);             // Weichzeichnen (0–100)
$image = $image->grayscale();         // Graustufen
$image = $image->sharpen(10);         // Schärfen (0–100)
$image = $image->flipVertically();    // Vertikal spiegeln
$image = $image->flipHorizontally();  // Horizontal spiegeln

Bedingte Transformationen

Bildinstanzen unterstützen den Conditionable-Trait, sodass sich mit when / unless bedingte Transformationen ausdrücken lassen.

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

Kodierung

Standardmäßig wird im ursprünglichen Format kodiert. Zum Konvertieren des Formats verwenden Sie die folgenden Methoden.

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

Mit der Methode quality können Sie die Ausgabequalität (1–100) festlegen.

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

Die Methode optimize ist ein Shortcut für Formatkonvertierung und Qualitätseinstellung. Voreinstellung sind WebP und Qualität 70.

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

Sie können die Ausgabe auch als Byte-String, Base64 oder Data URI erhalten.

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

Speichern

Mit der Methode store speichern Sie ein Bild auf einer Filesystem-Disk. Laravel generiert automatisch einen eindeutigen Dateinamen und gibt den Speicherpfad zurück.

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

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

Wenn Sie den Dateinamen selbst festlegen möchten, verwenden Sie storeAs.

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

Um mit der Sichtbarkeit public zu speichern, verwenden Sie 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');

Wenn das Speichern fehlschlägt, wird false zurückgegeben.

Bildinformationen abfragen

Mit den Methoden mimeType, extension, dimensions, width und height erhalten Sie Informationen zum Bild. Diese Methoden beziehen sich auf das bereits verarbeitete Bild (Beispiel: nach cover(400, 400) liefert width() den Wert 400).

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

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

Benutzerdefinierte Treiber

Der Image-Manager von Laravel erweitert Illuminate\Support\Manager. Über die Methode extend lassen sich eigene Treiber registrieren. Ein benutzerdefinierter Treiber implementiert das Interface Illuminate\Contracts\Image\Driver und erhält in der Methode process die ursprünglichen Bild-Bytes sowie die Pipeline und gibt die verarbeiteten Bild-Bytes zurück.

<?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
    {
        // Transformationen und Ausgabeoptionen der Pipeline anwenden...
        return $contents;
    }

    public function transformUsing(string $transformation, callable $callback): static
    {
        // Handler speichern, damit er während der Verarbeitung angewendet werden kann...
        return $this;
    }
}

Registriert wird der Treiber in der boot-Methode eines Service Providers.

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

Um für ein bestimmtes Bild einen anderen Treiber zu wählen, verwenden Sie die Methode using.

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

Benutzerdefinierte Transformationen

Über eine Klasse, die das Interface Illuminate\Contracts\Image\Transformation implementiert, können Sie eigene Transformationen definieren.

<?php

namespace App\Images\Transformations;

use Illuminate\Contracts\Image\Transformation;

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

Den Handler registrieren Sie in der boot-Methode eines Service Providers.

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

Nach der Registrierung wenden Sie die Transformation über die Methode transform an.

use App\Images\Transformations\Pixelate;

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

Architektur

Datenbank

Eloquent

Sicherheit

Ereignisse

E-Mail und Benachrichtigungen

Zahlungen

Asynchrone Verarbeitung

Echtzeitkommunikation

Zeitplanung

Caching und Optimierung

Internationalisierung

Dateien und Speicher

Debugging und Monitoring

Konsole und CLI

Performance

Frontend

KI-Entwicklung

Entwicklungsumgebung