Custom casts van Eloquent

Wat zijn casts?

Casts in Eloquent vormen het mechanisme dat ruwe waarden uit de database omzet naar PHP-datatypes en die omzetting bij het opslaan weer terugdraait. Je definieert ze met de casts-methode.

protected function casts(): array
{
    return [
        'is_admin'   => 'boolean',
        'settings'   => 'array',
        'created_at' => 'datetime',
    ];
}

Soorten ingebouwde casts

Een overzicht van de casts die Laravel standaard biedt.

Cast	Beschrijving
`integer` / `int`	Omzetten naar een geheel getal
`float` / `double`	Omzetten naar een kommagetal
`string`	Omzetten naar een string
`boolean` / `bool`	Omzetten naar een boolean (inclusief `0`/`1`)
`array`	JSON-string ↔ PHP-array
`collection`	JSON-string ↔ Collection-instantie
`object`	JSON-string ↔ stdObject-instantie
`datetime`	String ↔ Carbon-instantie
`immutable_datetime`	String ↔ CarbonImmutable-instantie
`date`	String ↔ Carbon (zonder tijd)
`timestamp`	String ↔ UNIX-timestamp
`encrypted`	Versleutelen bij opslaan, ontsleutelen bij ophalen
`hashed`	Hashen bij opslaan (te combineren met een alleen-lezen cast)
`AsStringable::class`	String ↔ Stringable-object
`AsArrayObject::class`	JSON ↔ ArrayObject-instantie
`AsCollection::class`	JSON ↔ Collection-instantie

AsArrayObject en AsCollection zijn binnen Laravel geïmplementeerd als custom casts, zodat je een specifieke offset van de array direct kunt wijzigen.

Een custom castklasse maken

Heb je een omzetting nodig die de ingebouwde casts niet aankunnen, dan maak je een custom cast die de interface CastsAttributes implementeert.

Definitie van de interface

Het contract in het framework zelf is als volgt gedefinieerd.

// src/Illuminate/Contracts/Database/Eloquent/CastsAttributes.php

interface CastsAttributes
{
    /**
     * Zet de ruwe DB-waarde om naar een PHP-waarde (bij lezen)
     *
     * @param  array<string, mixed>  $attributes  Alle attribuutwaarden van het model
     */
    public function get(Model $model, string $key, mixed $value, array $attributes);

    /**
     * Zet de PHP-waarde om naar een vorm die in de DB kan worden opgeslagen (bij schrijven)
     *
     * @param  array<string, mixed>  $attributes  Alle attribuutwaarden van het model
     */
    public function set(Model $model, string $key, mixed $value, array $attributes);
}

Het argument $attributes bevat alle attributen van het model, dus je kunt ook omzettingen over meerdere kolommen heen doen (zie het value-objectpatroon hieronder).

Implementatie van een basale custom cast

Genereer een sjabloon met het commando make:cast.

php artisan make:cast AsMoney

Er wordt een app/Casts/AsMoney.php gegenereerd. Als voorbeeld implementeren we een cast die een geldbedrag (opgeslagen als geheel getal) omzet naar het value object Money.

<?php

namespace App\Casts;

use App\ValueObjects\Money;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use Illuminate\Database\Eloquent\Model;

class AsMoney implements CastsAttributes
{
    /**
     * Zet de gehele DB-waarde (in yen) om naar een Money-object
     */
    public function get(
        Model $model,
        string $key,
        mixed $value,
        array $attributes,
    ): Money {
        return new Money((int) $value);
    }

    /**
     * Zet het Money-object om naar een geheel getal dat in de DB kan worden opgeslagen
     */
    public function set(
        Model $model,
        string $key,
        mixed $value,
        array $attributes,
    ): int {
        if ($value instanceof Money) {
            return $value->amount;
        }

        return (int) $value;
    }
}

Pas de cast toe op het model.

<?php

namespace App\Models;

use App\Casts\AsMoney;
use Illuminate\Database\Eloquent\Model;

class Order extends Model
{
    protected function casts(): array
    {
        return [
            'price' => AsMoney::class,
        ];
    }
}

Nu geeft $order->price een Money-instantie terug.

Value-objectcasts

Een patroon waarbij je meerdere DB-kolommen samen als één value object behandelt.

Implementatievoorbeeld: een adrescast

We bundelen de twee kolommen address_line_one en address_line_two in het value object Address.

<?php

namespace App\ValueObjects;

use Illuminate\Contracts\Support\Arrayable;

class Address implements Arrayable, \JsonSerializable
{
    public function __construct(
        public readonly string $lineOne,
        public readonly string $lineTwo,
    ) {}

    public function toArray(): array
    {
        return [
            'line_one' => $this->lineOne,
            'line_two' => $this->lineTwo,
        ];
    }

    public function jsonSerialize(): array
    {
        return $this->toArray();
    }
}

<?php

namespace App\Casts;

use App\ValueObjects\Address;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use Illuminate\Database\Eloquent\Model;
use InvalidArgumentException;

class AsAddress implements CastsAttributes
{
    /**
     * Stelt een Address-object samen uit meerdere kolommen
     */
    public function get(
        Model $model,
        string $key,
        mixed $value,
        array $attributes,
    ): Address {
        return new Address(
            $attributes['address_line_one'],
            $attributes['address_line_two'],
        );
    }

    /**
     * Splitst het Address-object op in een array per kolom
     *
     * @return array<string, string>
     */
    public function set(
        Model $model,
        string $key,
        mixed $value,
        array $attributes,
    ): array {
        if (! $value instanceof Address) {
            throw new InvalidArgumentException('The given value is not an Address instance.');
        }

        return [
            'address_line_one' => $value->lineOne,
            'address_line_two' => $value->lineTwo,
        ];
    }
}

Geef je in de set-methode een array terug, dan slaat Eloquent de sleutels op als kolomnamen en de waarden in de betreffende kolommen. Bij een cast voor een enkele kolom geef je een string of geheel getal terug.

Toepassing op het model en gebruik:

<?php

namespace App\Models;

use App\Casts\AsAddress;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected function casts(): array
    {
        return [
            'address' => AsAddress::class,
        ];
    }
}

$user = User::find(1);

// Ophalen als Address-object
echo $user->address->lineOne;

// Wijzig je het value object, dan wordt dit bij het opslaan automatisch doorgevoerd in de DB
$user->address = new Address('123 Main St', 'Apt 4B');
$user->save();

Caching van value objects

Attribuutwaarden die zijn omgezet naar een value object worden door Eloquent gecachet. Ook als je hetzelfde attribuut twee keer benadert, krijg je dezelfde objectinstantie terug. Wil je de caching uitschakelen, voeg dan de property $withoutObjectCaching toe aan de castklasse.

class AsAddress implements CastsAttributes
{
    public bool $withoutObjectCaching = true;

    // ...
}

Inbound casts (alleen-schrijven)

Een cast die alleen bij het schrijven naar de DB omzet en bij het lezen niets doet. Hiervoor implementeer je de interface CastsInboundAttributes. Een typische toepassing is hashen: alleen omzetten bij het opslaan van wachtwoorden of geheime waarden, en bij het lezen de hashwaarde ongewijzigd teruggeven.

php artisan make:cast AsHash --inbound

<?php

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsInboundAttributes;
use Illuminate\Database\Eloquent\Model;

class AsHash implements CastsInboundAttributes
{
    public function __construct(
        protected string|null $algorithm = null,
    ) {}

    /**
     * Hasht de waarde bij het opslaan
     */
    public function set(
        Model $model,
        string $key,
        mixed $value,
        array $attributes,
    ): string {
        return is_null($this->algorithm)
            ? bcrypt($value)
            : hash($this->algorithm, $value);
    }
}

Castparameters

Wil je parameters doorgeven aan een custom cast, dan zet je die achter de klassenaam, gescheiden door een dubbele punt. Meerdere parameters scheid je met komma’s.

protected function casts(): array
{
    return [
        'secret' => AsHash::class.':sha256',
        'data'   => AsHash::class.':sha512',
    ];
}

De parameters worden doorgegeven aan de constructor van de castklasse.

class AsHash implements CastsInboundAttributes
{
    public function __construct(
        protected string|null $algorithm = null, // ':sha256' wordt doorgegeven
    ) {}
}

Castables: de castlogica bij het value object leggen

Een value object dat de interface Castable implementeert, heeft een castUsing-methode die zijn eigen castklasse teruggeeft. Het model hoeft de castklasse dan niet te kennen, wat de domeinlogica overzichtelijker maakt.

<?php

namespace App\ValueObjects;

use App\Casts\AsAddress;
use Illuminate\Contracts\Database\Eloquent\Castable;

class Address implements Castable
{
    /**
     * Geeft de klasse terug die voor het casten van dit object wordt gebruikt
     *
     * @param  array<string, mixed>  $arguments
     */
    public static function castUsing(array $arguments): string
    {
        return AsAddress::class;
    }
}

Aan de modelkant geef je in plaats van de castklasse de value-objectklasse op.

protected function casts(): array
{
    return [
        'address' => Address::class,
    ];
}

Combineer je Castable met een anonieme klasse, dan kun je het value object en de castlogica in één bestand bundelen.

class Address implements Castable
{
    public static function castUsing(array $arguments): CastsAttributes
    {
        return new class implements CastsAttributes
        {
            public function get(Model $model, string $key, mixed $value, array $attributes): Address
            {
                return new Address(
                    $attributes['address_line_one'],
                    $attributes['address_line_two'],
                );
            }

            public function set(Model $model, string $key, mixed $value, array $attributes): array
            {
                return [
                    'address_line_one' => $value->lineOne,
                    'address_line_two' => $value->lineTwo,
                ];
            }
        };
    }
}

Interactie met `$appends` en `$hidden`

Casts en $appends / $hidden zijn onafhankelijke mechanismen, maar bij het combineren moet je opletten.

class User extends Model
{
    protected function casts(): array
    {
        return [
            'address' => AsAddress::class,
        ];
    }

    // Sluit address uit bij toArray() / toJson()
    protected $hidden = ['address_line_one', 'address_line_two'];

    // Neem het gecaste address op in het serialisatieresultaat
    protected $appends = ['address'];
}

In $hidden geef je de DB-kolomnamen op. Niet de attribuutnaam die via de cast ontstaat (address), maar de oorspronkelijke kolomnamen (address_line_one, address_line_two).

Casts toevoegen tijdens runtime

Wil je alleen voor een specifieke query of request een cast toevoegen, gebruik dan de methode mergeCasts.

$user = User::find(1);

$user->mergeCasts([
    'extra_data' => 'array',
]);

Volgende stap

Eloquent-observers en modelevents

Leer hoe je inhaakt op lifecycle-events van modellen, zoals opslaan en verwijderen, om extra verwerking toe te voegen.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Wat zijn casts?

Soorten ingebouwde casts

Een custom castklasse maken

Definitie van de interface

Implementatie van een basale custom cast

Value-objectcasts

Implementatievoorbeeld: een adrescast

Caching van value objects

Inbound casts (alleen-schrijven)

Castparameters

Castables: de castlogica bij het value object leggen

Interactie met `$appends` en `$hidden`

Casts toevoegen tijdens runtime

Volgende stap

Eloquent-observers en modelevents

​Wat zijn casts?

​Soorten ingebouwde casts

​Een custom castklasse maken

​Definitie van de interface

​Implementatie van een basale custom cast

​Value-objectcasts

​Implementatievoorbeeld: een adrescast

​Caching van value objects

​Inbound casts (alleen-schrijven)

​Castparameters

​Castables: de castlogica bij het value object leggen

​Interactie met $appends en $hidden

​Casts toevoegen tijdens runtime

​Volgende stap

Eloquent-observers en modelevents

Wat zijn casts?

Soorten ingebouwde casts

Een custom castklasse maken

Definitie van de interface

Implementatie van een basale custom cast

Value-objectcasts

Implementatievoorbeeld: een adrescast

Caching van value objects

Inbound casts (alleen-schrijven)

Castparameters

Castables: de castlogica bij het value object leggen

Interactie met `$appends` en `$hidden`

Casts toevoegen tijdens runtime

Volgende stap