Laravel 14 aggiunge un metodo defaults() ai modelli Eloquent

I modelli Eloquent impostano i valori predefiniti degli attributi con la proprietà $attributes. Funziona per i valori fissi, ma PHP consente solo espressioni costanti nel valore predefinito di una proprietà, quindi non è possibile chiamare config(), now() o un feature flag in quel punto. Laravel 14 aggiunge un metodo defaults() che restituisce lo stesso array da codice eseguito al momento della creazione del modello.

Prima e dopo

Prendiamo un modello subscription che assegna alle nuove sottoscrizioni un periodo di prova di 14 giorni, e di 30 giorni quando è attivo un feature flag extended-trials. Con $attributes, il flag deve essere verificato nel costruttore:

class Subscription extends Model
{
protected $attributes = [
'cancelled' => false,
'trial_days' => 14,
];

public function __construct(array $attributes = [])
{
if (Feature::active('extended-trials')) {
$this->attributes['trial_days'] = 30;
}

parent::__construct($attributes);
}
}

In Laravel 14, la stessa logica va in defaults():

class Subscription extends Model
{
protected function defaults(): array
{
return [
'cancelled' => false,
'trial_days' => Feature::active('extended-trials') ? 30 : 14,
'expires_at' => now()->addDays(config('billing.grace_period'))->toDateTimeString(),
];
}
}

$subscription = new Subscription;

$subscription->trial_days; // 30 when the flag is active, 14 otherwise

Laravel 11 ha fatto la stessa cosa per i casts, quando lo skeleton dell'applicazione è passato dalla proprietà $casts a un metodo casts() (Model Casts are moving to methods in Laravel 11). defaults() fornisce anche a $attributes una versione come metodo.

Come funziona

Il costruttore del modello chiama defaults() e unisce il risultato in $attributes. L'ordine nel costruttore determina quale valore prevale:

1. I valori della proprietà $attributes vengono impostati per primi
2. defaults() viene unito sopra di essi, quindi prevale quando entrambi definiscono la stessa chiave
3. Gli attributi passati a new, create() o fill() vengono applicati per ultimi, quindi prevalgono su entrambi

$subscription = Subscription::create(['trial_days' => 60]);

$subscription->trial_days; // 60

I valori predefiniti vengono uniti prima che il modello sincronizzi i suoi attributi originali, quindi non contano come modifiche dirty. Vengono comunque scritti nel database quando il modello viene inserito, esattamente come $attributes.

Valori raw

Come $attributes, i valori di defaults() sono raw. Non passano attraverso casts o mutators. Restituire il valore così come verrebbe memorizzato nel database:

protected function defaults(): array
{
return [
// A column cast to `array` expects a JSON string
'settings' => json_encode(['theme' => 'light']),

// A date column
'expires_at' => now()->addDays(30)->toDateTimeString(),
];
}

Restituire un array PHP per una colonna cast a array o json fallisce quando l'attributo viene letto, perché il cast si aspetta una stringa JSON.

Quando viene eseguito defaults()

Il metodo defaults() viene eseguito ogni volta che viene costruita un'istanza del modello. Questo include i modelli caricati dal database. Eloquent costruisce ogni riga recuperata con una nuova istanza del modello, quindi defaults() viene eseguito una volta per riga, e poi i valori della riga sostituiscono quelli predefiniti.

Aggiornamento

Il metodo è destinato a Laravel 14 perché un modello esistente potrebbe già avere un metodo chiamato defaults(). In Laravel 14, il costruttore lo chiama e unisce ciò che restituisce negli attributi. Prima di aggiornare, cerca nei tuoi modelli un metodo con quel nome:

grep -rn "function defaults" app/Models

Rinomina qualsiasi metodo che non sia pensato per restituire valori predefiniti degli attributi.

Jack Bayliss ha contribuito al metodo in #61688. È stato unito nel branch master e può cambiare prima del rilascio di Laravel 14.

Letture successive

• What We Know About Laravel 14
• Model Casts are moving to methods in Laravel 11
• New Expressive Model Attributes in Laravel 13.2.0
• Refresh Generated Columns After Saving an Eloquent Model