← Chargement anticipé · Retour au README · Conversions des données →

Configuration

Publier la configuration

php artisan vendor:publish --tag="model_settings"

Cette commande publie config/model_settings.php et la migration du paquet.

Options disponibles

Option	Valeur par défaut	Rôle
`model`	`DragonCode\LaravelModelSettings\Models\Settings`	Modèle Eloquent utilisé pour les paramètres stockés
`connection`	Valeur par défaut de l’application	Connexion utilisée par le modèle et la migration
`table`	`settings`	Table utilisée par le modèle et la migration
`casts`	`[]`	Conversions sélectionnées selon la classe du modèle parent et, facultativement, la clé

Le paquet lit les variables d’environnement suivantes :

Variable	Valeur par défaut
`MODEL_SETTINGS_DATABASE_CONNECTION`	`DATABASE_CONNECTION`, puis la connexion par défaut de Laravel
`MODEL_SETTINGS_DATABASE_TABLE`	`settings`

Définissez la connexion et la table avant d’exécuter la migration :

MODEL_SETTINGS_DATABASE_CONNECTION=mysql
MODEL_SETTINGS_DATABASE_TABLE=model_settings

La modification ultérieure de l’une de ces valeurs ne déplace pas les enregistrements existants.

Configuration des conversions

L’ancienne forme à l’échelle du modèle reste prise en charge. Une conversion traite toutes les données appartenant à la classe du modèle :

'casts' => [
    App\Models\User::class => App\Casts\UserSettingsPayloadCast::class,
],

Utilisez une table indexée par clé lorsque différentes clés nécessitent des types ou traitements distincts :

'casts' => [
    App\Models\User::class => [
        'profile' => App\Data\ProfileData::class,
        'billing.credentials' => App\Casts\EncryptedSettingPayload::class,
    ],
],

La correspondance des clés est exacte. Les points ne représentent aucun chemin imbriqué et une clé absente de la table utilise la conversion JSON par défaut. Chaque entrée de modèle est soit une chaîne de classe pour tout le modèle, soit une table indexée par clé ; aucun caractère générique n’existe dans cette table. Consultez Conversions des données pour les contrats pris en charge et une recette de chiffrement.

Schéma de stockage

La migration publiée crée les colonnes suivantes :

Colonne	Rôle
`id`	Clé primaire de la ligne de paramètre
`item_type`	Classe morph ou alias du modèle parent
`item_id`	Identifiant du parent, stocké sous forme de chaîne de 36 caractères maximum
`is_default`	Distingue les valeurs par défaut de classe des surcharges de modèles
`key`	Clé du paramètre
`payload`	Données déclarées comme `jsonb` par la migration
`created_at` et `updated_at`	Horodatages Laravel

La combinaison de item_type, item_id, is_default et key est unique. Un index de recherche sur item_type, is_default et item_id prend en charge les lectures des valeurs par défaut et de la portée du propriétaire.

Les valeurs par défaut de classe et les surcharges de modèles partagent cette table. Le paquet ne crée aucune seconde table de valeurs par défaut et n’ajoute aucune colonne de métadonnées de chiffrement.

La colonne item_id par défaut stocke au maximum 36 caractères. Les identifiants entiers, chaînes, UUID et ULID tiennent dans ce schéma lorsque leur représentation sous forme de chaîne ne dépasse pas 36 caractères. Une clé primaire personnalisée plus longue nécessite une modification correspondante de la migration.

Les valeurs par défaut de la classe utilisent item_id = '0' avec is_default = true. Un propriétaire enregistré dont la clé est l’entier 0 ou la chaîne '0' utilise le même item_id physique avec is_default = false. Les deux lignes peuvent donc coexister pour le même type de modèle et la même clé de paramètre. Si des données existent déjà, la modification de la connexion, du nom de table ou des alias de morph map nécessite de déplacer ou de mettre à jour vous-même les lignes existantes.

Mise à niveau depuis une version 1.x antérieure

Cette version modifie le contrat d’exécution en plus de la migration du discriminateur de stockage :

Comportement des versions 1.x antérieures	Comportement actuel	Modification requise dans l’application
`set($key, null)`, les chaînes vides ou composées d’espaces et les tableaux vides supprimaient la ligne	`set()` stocke chaque valeur JSON exactement	Remplacez les appels de suppression par `forget($key)`
Les entrées vides de `setMany()` étaient supprimées dans le même lot	Chaque entrée de `setMany()` est stockée dans un upsert transactionnel unique	Placez les clés à supprimer dans un appel `forgetMany()` séparé
Les clés vides ou composées uniquement d’espaces étaient acceptées	Les clés normalisées vides lèvent `InvalidSettingKey`	Renommez ou supprimez les clés invalides avant la mise à niveau
Les tests d’existence nécessitaient `all()->has($key)`	`has($key)` distingue le JSON `null` stocké d’une clé absente	Préférez la méthode ciblée `has()`

Une surcharge de modèle null stockée masque désormais une valeur par défaut de classe non vide jusqu’à sa suppression avec forget(). Les conversions personnalisées reçoivent maintenant les valeurs vides des deux méthodes d’écriture, et les événements de création ou de mise à jour d’un modèle de stockage personnalisé les reçoivent depuis set(). get() accepte toujours un seul argument ; aucun repli fourni par l’appelant ni alias permanent put() n’a été ajouté.

Après la mise à jour du paquet, publiez sa nouvelle migration et exécutez-la pendant que l’application est en mode maintenance :

php artisan vendor:publish --tag="model_settings"
php artisan migrate

La migration ajoute is_default, classe chaque ancienne ligne avec item_id = '0' comme valeur par défaut de classe, crée les index tenant compte du discriminateur, puis supprime l’ancien index unique. Elle n’écrit jamais les clés ni les données des paramètres dans sa sortie.

Les anciens schémas 1.x encodaient de la même façon les valeurs par défaut de classe et les lignes d’un véritable propriétaire d’identifiant 0. La migration ne peut donc pas distinguer une surcharge de propriétaire insérée manuellement d’une valeur par défaut et classe les deux comme valeurs par défaut. Après la migration, vérifiez les anciennes données connues des propriétaires d’identifiant 0 et définissez is_default = false pour les lignes qui sont réellement des surcharges de modèle.

N’exécutez pas l’ancienne version du paquet avec le schéma mis à niveau. Elle n’écrit pas le discriminateur et enregistrerait les valeurs par défaut comme des surcharges. Déployez la migration et la version compatible du paquet dans une même fenêtre de maintenance.

Le retour arrière n’est sûr qu’avant la création d’une véritable surcharge de propriétaire d’identifiant 0. La migration s’arrête avant de modifier le schéma si elle trouve item_id = '0' avec is_default = false, car l’ancien schéma ne peut pas représenter cette ligne sans en changer le sens. Supprimez ou exportez ces surcharges avant le retour arrière. Un retour arrière sûr restaure l’ancien index unique et supprime is_default.

Remplacer le modèle de stockage

Le modèle de paramètres intégré est final. Configurez un remplacement au lieu d’en hériter :

namespace App\Models;

use DragonCode\LaravelModelSettings\Casts\PayloadCast;
use Illuminate\Database\Eloquent\Model;

final class ApplicationSetting extends Model
{
    protected $fillable = [
        'item_type',
        'item_id',
        'is_default',
        'key',
        'payload',
    ];

    public function __construct(array $attributes = [])
    {
        $this->setConnection(config('model_settings.connection'));
        $this->setTable(config('model_settings.table'));

        parent::__construct($attributes);
    }

    protected function casts(): array
    {
        return [
            'item_id'    => 'string',
            'is_default' => 'boolean',
            'payload'    => PayloadCast::class,
        ];
    }
}

Mettez ensuite la configuration à jour :

'model' => App\Models\ApplicationSetting::class,

Le remplacement doit rester compatible avec le schéma publié. Conservez les attributs remplissables et PayloadCast, sauf si le nouveau modèle implémente une sérialisation équivalente.

Le modèle de remplacement doit au minimum conserver les comportements suivants :

Exigence	Raison
Remplir `item_type`, `item_id`, `is_default`, `key` et `payload`	Le stockage écrit ces attributs
Utiliser la connexion et la table configurées	La migration et le dépôt doivent accéder aux mêmes lignes
Convertir `item_id` en `string`	Les entiers, chaînes, UUID et ULID partagent une colonne
Convertir `is_default` en `boolean`	Les résolutions différée et anticipée doivent lire le même discriminateur de portée
Convertir `payload` avec `PayloadCast` ou un équivalent	Les lectures et écritures doivent conserver le comportement JSON

Voir aussi

Premiers pas — publier la configuration et la migration.
Conversions des données — configurer des types de données propres à l’application.
Référence de l’API — consulter l’interface publique du paquet.

Publier la configuration​

Options disponibles​

Configuration des conversions​

Schéma de stockage​

Mise à niveau depuis une version 1.x antérieure​

Remplacer le modèle de stockage​

Voir aussi​