Casty a šifrovanie

castAs() určuje, ako sa uložená hodnota číta a zapisuje. Prijme ľubovoľný cast Laravelu ako reťazec, vlastný CastsAttributes (class-string alebo inštanciu) alebo class-string castu s parametrami:

public function castAs(): string|CastsAttributes
{
    return 'boolean'; // integer, float, array, collection, immutable_datetime, …
}

Dátumy sa vracajú ako inštancie Carbon:

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use RoundlyConsulting\Options\BaseOption;

final class TrialEndsAtOption extends BaseOption
{
    public function key(): string
    {
        return 'trial-ends-at';
    }

    public function castAs(): string|CastsAttributes
    {
        return 'immutable_datetime';
    }
}

TrialEndsAtOption::for($team)->set(now()->toImmutable()->addDays(14));
TrialEndsAtOption::for($team)->value(); // CarbonImmutable

Backed enumy

EnumCast pretypuje hodnotu na backed enum a späť — so string aj int hodnotami. Triedu enumu odovzdajte ako parameter castu:

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use RoundlyConsulting\Options\BaseOption;
use RoundlyConsulting\Options\Casts\EnumCast;

enum Status: string
{
    case Active = 'active';
    case Paused = 'paused';
}

final class StatusOption extends BaseOption
{
    public function key(): string
    {
        return 'status';
    }

    public function castAs(): string|CastsAttributes
    {
        return EnumCast::class.':'.Status::class; // backed-enum cast (string- or int-backed)
    }
}

Options::set(StatusOption::class, Status::Paused);  // stores 'paused'
Options::get(StatusOption::class);                 // Status::Paused

Ukladá hodnotu, ktorá stojí za enumom, a vracia prípad (case). Pri enume s int hodnotami sa číselný reťazec z textového stĺpca najprv prevedie na int. set() prijme case aj surovú skalárnu hodnotu; prázdna uložená hodnota sa prečíta ako null a uložená hodnota, ktorá už nezodpovedá žiadnemu prípadu, sa namiesto výnimky prečíta tiež ako null. Môžete vrátiť aj new EnumCast(Status::class) — inštanciu castu však nemožno šifrovať a v definíciách skupín sa zobrazí s typom custom.

Šifrovanie

Ak encrypted() vráti true, hodnota sa v úložisku zašifruje. Serializuje sa cez svoj cast, zašifruje enkryptorom Laravelu a pri čítaní sa dešifruje a pretypuje späť — šifrované nastavenie s castom integer sa teda prečíta ako int:

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use RoundlyConsulting\Options\BaseOption;

final class ApiTokenOption extends BaseOption
{
    public function key(): string
    {
        return 'api-token';
    }

    public function castAs(): string|CastsAttributes
    {
        return 'string'; // must be a string when encrypted
    }

    public function encrypted(): bool
    {
        return true;
    }
}

Options::set(ApiTokenOption::class, 'tok_example_123', $tenant); // ciphertext at rest
Options::get(ApiTokenOption::class, $tenant);                    // 'tok_example_123'

• Pri encrypted() = true musí castAs() vracať reťazec — 'integer', 'boolean', 'collection', class-string castu ako EnumCast::class.':'.Status::class, … Inštancia castu vyhodí EncryptionNotSupported.
• Každý cast sa vráti v pôvodnom type: vnútorný cast hodnotu pred zašifrovaním serializuje a po dešifrovaní ju znova pretypuje, takže celé čísla, booleany, dátumy, kolekcie aj enumy prídu späť vo svojom type.
• Šifruje sa kľúčom APP_KEY. Pozmenený šifrový text pri čítaní vyhodí DecryptException z Laravelu.
• Pamäť requestu aj trvalá cache držia vždy len šifrový text — cache úložisko čitateľnú hodnotu nikdy neuvidí.
• Eventy, observery aj definície skupín vidia hodnotu v čitateľnej podobe — dajte si pozor, čo logujete.

Čítanie vždy vráti typ castu

set() uloží hodnotu tak, ako by ju uložila databáza — ako surový reťazec, ktorý vytvorí jej cast — a do cache dá práve ten, nie váš vstup. Každé čítanie ho pretypuje, aj to hneď po set(): „active“ uložené do enumového nastavenia vráti Status::Active, nastavenie s castom integer s hodnotou „5“ vráti 5 a nastavenie s castom collection, do ktorého uložíte pole, vráti Collection. Aj options:set, ktorý odovzdá reťazec (alebo s --json dekódovaný JSON), sa tak hneď prečíta v type nastavenia.