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

# Eloquent-Serialisierung

> Erläutert, wie Sie Eloquent-Modelle in JSON und Arrays konvertieren, das Ein- und Ausblenden von Attributen steuern, zusätzliche Attribute anhängen und Datumsformate anpassen.

## Einführung

Beim Aufbau einer API mit Laravel müssen Sie Modelle und ihre Relationen häufig in Arrays oder JSON umwandeln.
Eloquent bringt praktische Methoden für diese Umwandlung mit sowie Funktionen, mit denen Sie steuern, welche Attribute in der serialisierten Darstellung enthalten sind.

<Info>
  Eine robustere Möglichkeit, Eloquent-Modelle und -Collections nach JSON zu serialisieren, bietet die Dokumentation zu [Eloquent-API-Ressourcen](./eloquent-resources).
</Info>

## Modelle und Arrays

### Serialisierung in ein Array

Um ein Modell und seine geladenen [Relationen](./eloquent-relationships) in ein Array umzuwandeln, verwenden Sie die Methode `toArray`.
Die Methode arbeitet rekursiv: Alle Attribute und alle Relationen (inklusive verschachtelter Relationen) werden in ein Array überführt.

```php theme={null}
use App\Models\User;

$user = User::with('roles')->first();

return $user->toArray();
```

Mit `attributesToArray` konvertieren Sie ausschließlich die Attribute des Modells, ohne Relationen.

```php theme={null}
$user = User::first();

return $user->attributesToArray();
```

Eine gesamte Modell-Collection wandeln Sie über die Methode `toArray` der Collection-Instanz in ein Array um.

```php theme={null}
$users = User::all();

return $users->toArray();
```

### Serialisierung in JSON

Mit der Methode `toJson` wandeln Sie ein Modell in JSON um.
Wie `toArray` arbeitet `toJson` rekursiv – alle Attribute und Relationen werden in JSON überführt.
Sie können die [von PHP unterstützten JSON-Kodierungsoptionen](https://secure.php.net/manual/en/function.json-encode.php) übergeben.

```php theme={null}
use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);
```

Sie können ein Modell oder eine Collection auch in einen String casten; dabei wird intern `toJson` aufgerufen.

```php theme={null}
return (string) User::find(1);
```

Da Modelle und Collections beim Cast zu einem String in JSON umgewandelt werden, können Sie Eloquent-Objekte direkt aus Routen oder Controllern zurückgeben.
Laravel serialisiert von Routen oder Controllern zurückgegebene Eloquent-Modelle und -Collections automatisch nach JSON.

```php theme={null}
Route::get('/users', function () {
    return User::all();
});
```

#### Relationen

Wenn ein Eloquent-Modell in JSON umgewandelt wird, tauchen bereits geladene Relationen automatisch als Attribute im JSON-Objekt auf.
Auch wenn Eloquent-Relationsmethoden im CamelCase definiert sind, verwenden ihre JSON-Attributnamen die Snake-Case-Schreibweise.

## Sichtbarkeit von Attributen steuern

### Attribute ausblenden

Manchmal möchten Sie in der Array- oder JSON-Darstellung eines Modells bestimmte Attribute – etwa Passwörter – ausblenden.
Verwenden Sie hierfür das Attribut `Hidden` auf dem Modell.
Attribute, die in `Hidden` aufgelistet sind, erscheinen nicht in der serialisierten Darstellung.

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Model;

#[Hidden(['password'])]
class User extends Model
{
    // ...
}
```

<Info>
  Um Relationen auszublenden, tragen Sie den Namen der Relationsmethode in das `Hidden`-Attribut ein.
</Info>

### Attribute freigeben

Mit dem Attribut `Visible` legen Sie eine „Whitelist" der Attribute fest, die in Array- und JSON-Darstellungen enthalten sein sollen.
Alle Attribute, die nicht in `Visible` aufgelistet sind, werden bei der Umwandlung in ein Array oder JSON ausgeblendet.

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Visible;
use Illuminate\Database\Eloquent\Model;

#[Visible(['first_name', 'last_name'])]
class User extends Model
{
    // ...
}
```

### Attribute temporär ein-/ausblenden

Um normalerweise verborgene Attribute auf einer bestimmten Modellinstanz sichtbar zu machen, verwenden Sie `makeVisible` oder `mergeVisible`.
`makeVisible` liefert die Modellinstanz zurück.

```php theme={null}
return $user->makeVisible('attribute')->toArray();

return $user->mergeVisible(['name', 'email'])->toArray();
```

Umgekehrt können Sie ansonsten sichtbare Attribute mit `makeHidden` oder `mergeHidden` verbergen.

```php theme={null}
return $user->makeHidden('attribute')->toArray();

return $user->mergeHidden(['name', 'email'])->toArray();
```

Um sichtbare oder verborgene Attribute vollständig zu überschreiben, verwenden Sie `setVisible` bzw. `setHidden`.

```php theme={null}
return $user->setVisible(['id', 'name'])->toArray();

return $user->setHidden(['email', 'password', 'remember_token'])->toArray();
```

## Angehängte Attribute (Appends)

Bei der Umwandlung eines Modells in ein Array oder JSON möchten Sie manchmal Attribute hinzufügen, für die es keine passende Datenbankspalte gibt.
Definieren Sie dazu zunächst einen [Accessor](./eloquent-mutators) für den gewünschten Wert.

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Bestimme, ob der Benutzer Administrator ist.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}
```

Wenn der Accessor immer in Array- und JSON-Darstellungen des Modells enthalten sein soll, verwenden Sie am Modell das Attribut `Appends`.
Die PHP-Methode für den Accessor ist im CamelCase definiert; der Attributname folgt in der Serialisierung üblicherweise dem Snake-Case.

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Appends;
use Illuminate\Database\Eloquent\Model;

#[Appends(['is_admin'])]
class User extends Model
{
    // ...
}
```

Sobald ein Attribut in der `appends`-Liste steht, taucht es sowohl in der Array- als auch in der JSON-Darstellung auf.
Auch Einträge in `appends` unterliegen den `visible`- und `hidden`-Einstellungen des Modells.

### Zur Laufzeit anhängen

Zur Laufzeit können Sie einer Modellinstanz mit `append` oder `mergeAppends` zusätzliche Attribute anhängen.
Mit `setAppends` überschreiben Sie das gesamte Array angehängter Eigenschaften für eine bestimmte Modellinstanz.

```php theme={null}
return $user->append('is_admin')->toArray();

return $user->mergeAppends(['is_admin', 'status'])->toArray();

return $user->setAppends(['is_admin'])->toArray();
```

Um alle angehängten Eigenschaften wieder zu entfernen, verwenden Sie `withoutAppends`.

```php theme={null}
return $user->withoutAppends()->toArray();
```

## Datumsserialisierung

### Standard-Datumsformat anpassen

Durch Überschreiben der Methode `serializeDate` passen Sie das Standard-Serialisierungsformat an.
Auf das Speicherformat in der Datenbank hat diese Methode keinen Einfluss.

```php theme={null}
/**
 * Bereite ein Datum für die Array-/JSON-Serialisierung vor.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}
```

### Formatierung pro Attribut anpassen

Über die [Cast-Deklarationen](./eloquent-mutators#attribute-casting) des Modells legen Sie das Serialisierungsformat einzelner Datumsattribute fest.

```php theme={null}
protected function casts(): array
{
    return [
        'birthday' => 'date:Y-m-d',
        'joined_at' => 'datetime:Y-m-d H:00',
    ];
}
```


## Related topics

- [Eloquent-Collections](/de/eloquent-collections.md)
- [Eloquent: Accessors, Mutators, Casts](/de/eloquent-mutators.md)
- [Upgrade-Anleitung von Laravel 12 auf 13](/de/blog/upgrade-12-to-13.md)
- [Redis](/de/redis.md)
- [Übersicht der neuen Features in Laravel 13](/de/blog/laravel-13-new-features.md)