Laravel 14 : les valeurs par défaut lisent la config

Ce qui se passe

La propriété $attributes d'un modèle Eloquent fixe ses valeurs par défaut. Elle a une limite qui ne vient pas de Laravel mais de PHP : la valeur initiale d'une propriété doit être une expression constante. Pas de config(), pas de now(), pas de feature flag ; on surchargeait donc le constructeur.

Laravel 14 ajoute une méthode defaults(), qui renvoie le même tableau mais s'exécute à la création du modèle. C'est le chemin qu'avaient suivi les casts avec Laravel 11, passés de $casts à casts(). La méthode est signée Jack Bayliss (PR #61688).

class Invoice extends Model
{
    protected function defaults(): array
    {
        return [
            'currency' => config('billing.currency'),
            'due_at' => now()->addDays(config('billing.terms'))->toDateTimeString(),
            'options' => json_encode(['reminders' => true]),
        ];
    }
}

Qui l'emporte

1. la propriété $attributes ;
2. defaults(), fusionné par-dessus ;
3. les valeurs passées à new, create() ou fill(), appliquées en dernier.

Les défauts sont posés avant que le modèle mémorise son état d'origine : ils ne sont pas vus comme des modifications, mais partent bien en base à l'insertion.

Deux limites

Des valeurs brutes. Ni cast ni mutateur ne s'appliquent : on renvoie ce qui sera stocké. Pour une colonne castée en array ou json, une chaîne JSON — un tableau PHP fait échouer la lecture de l'attribut. Pour une date, une chaîne.

Un appel par instance. defaults() tourne à chaque construction, y compris pour chaque ligne chargée depuis la base, avant que les valeurs lues ne remplacent les défauts. Une méthode qui interroge la base ou le réseau le ferait donc à chaque ligne.

Avant de monter de version

Une méthode defaults() qui existe déjà dans un de vos modèles, pour un tout autre usage, sera appelée par le constructeur et son résultat fusionné dans les attributs. C'est la raison pour laquelle le changement vise une version majeure.

grep -rn "function defaults" app/Models

Renommez ce qui ne renvoie pas des valeurs par défaut. La fonction est fusionnée dans master et peut encore évoluer d'ici la sortie de Laravel 14.

Source : Laravel 14 Adds a defaults() Method to Eloquent Models, Laravel News, 30 septembre 2026.