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

# Bildbearbeitung

> Erfahren Sie, wie Sie mit der Image-Facade von Laravel Bilder skalieren, zuschneiden, konvertieren und speichern.

## 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](https://image.intervention.io/) zum Einsatz, das sowohl die PHP-Extension GD als auch Imagick unterstützt.

```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>
  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](/de/queues) in Betracht.
</Warning>

<Info>
  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.
</Info>

## Installation

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

```shell theme={null}
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.

```shell theme={null}
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`.

```ini theme={null}
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.

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

    // ...
});
```

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

```php theme={null}
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.

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

### Dateien aus dem Storage

Um eine Bildinstanz aus einer auf einem [Filesystem-Disk](/de/filesystem) gespeicherten Datei zu erzeugen, verwenden Sie die Methode `fromStorage`. Das erste Argument ist der Dateipfad, das zweite der Disk-Name.

```php theme={null}
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.

```php theme={null}
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.

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

## Bildbearbeitung

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.

```php theme={null}
$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                                        |

```php theme={null}
$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

```php theme={null}
$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.

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

## Kodierung

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

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

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

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

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

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

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

```php theme={null}
$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.

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

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

```php theme={null}
$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`.

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

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

```php theme={null}
$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 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
    {
        // 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.

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

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

```php theme={null}
$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 theme={null}
<?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.

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

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

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

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


## Related topics

- [Amazon-Bedrock-Treiber für das Laravel AI SDK](/de/packages/laravel-amazon-bedrock.md)