如何在Laravel中创建类似tcg/voyager的全局设置模型

1. 创建Settings表迁移文件 #

先生成迁移文件用于存储配置项：

php artisan make:migration create_settings_table

编辑生成的迁移文件，定义表结构：

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up()
    {
        Schema::create('settings', function (Blueprint $table) {
            $table->id();
            $table->string('key')->unique(); // 存储`site.title`这类键名
            $table->text('value')->nullable(); // 存储配置值
            $table->timestamps();
        });
    }

    public function down()
    {
        Schema::dropIfExists('settings');
    }
};

执行迁移生成表：

php artisan migrate

2. 创建Setting模型 #

生成模型并实现配置的缓存、读写逻辑：

php artisan make:model Setting

编辑app/Models/Setting.php：

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Facades\Cache;

class Setting extends Model
{
    protected $fillable = ['key', 'value'];

    // 缓存标识
    const CACHE_KEY = 'settings_cache';

    /**
     * 获取所有配置并永久缓存
     */
    public static function allSettings()
    {
        return Cache::rememberForever(self::CACHE_KEY, function () {
            return self::pluck('value', 'key')->toArray();
        });
    }

    /**
     * 更新或创建配置项，更新后清除缓存
     */
    public static function set($key, $value)
    {
        self::updateOrCreate(['key' => $key], ['value' => $value]);
        Cache::forget(self::CACHE_KEY);
    }

    /**
     * 获取单个配置项，支持默认值
     */
    public static function get($key, $default = null)
    {
        $settings = self::allSettings();
        return $settings[$key] ?? $default;
    }
}

3. 创建全局辅助函数setting() #

在app/Helpers/目录下创建setting.php文件，添加辅助函数：

<?php

if (!function_exists('setting')) {
    /**
     * 读取或设置配置项
     */
    function setting($key, $value = null)
    {
        if (is_null($value)) {
            return \App\Models\Setting::get($key);
        }

        \App\Models\Setting::set($key, $value);
        return $value;
    }
}

修改composer.json的autoload配置，让系统自动加载这个辅助文件：

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/"
    },
    "files": [
        "app/Helpers/setting.php"
    ]
},

更新自动加载规则：

composer dump-autoload

4. 初始化默认配置（可选） #

生成Seeder批量初始化配置：

php artisan make:seeder SettingsSeeder

编辑database/seeders/SettingsSeeder.php：

namespace Database\Seeders;

use App\Models\Setting;
use Illuminate\Database\Seeder;

class SettingsSeeder extends Seeder
{
    public function run()
    {
        $defaultSettings = [
            'site.title' => '我的Laravel站点',
            'site.description' => '基于Laravel搭建的站点',
            'site.footer_text' => '© 2025 版权所有',
        ];

        foreach ($defaultSettings as $key => $value) {
            Setting::set($key, $value);
        }
    }
}

执行Seeder导入数据：

php artisan db:seed --class=SettingsSeeder

5. 使用示例 #

• 读取配置：

// 获取站点标题
echo setting('site.title');

// 读取不存在的配置时返回默认值
echo setting('site.not_exists', '默认内容');

• 更新/创建配置：

// 修改站点标题
setting('site.title', '全新的站点名称');

进阶优化建议（可选） #

• 给配置项添加type字段（如string、integer、array），在模型中实现自动序列化/反序列化
• 搭建后台配置管理页面，实现可视化编辑
• 监听配置变更事件，自动刷新缓存

内容的提问来源于stack exchange，提问作者D .MOTAHARI