تنظیمات (Settings)

معرفی

بخش Settings برای ذخیره و مدیریت تنظیمات قابل تغییر پروژه در دیتابیس استفاده می‌شود.

این تنظیمات بدون نیاز به تغییر کد یا دیپلوی مجدد قابل ویرایش هستند و می‌توانند هم در پنل و هم در API استفاده شوند.

---

ساختار دیتابیس

جدول settings

فیلد	نوع	توضیح
id	id	شناسه یکتا
code	string(100)	کد تنظیم (Unique – مورد استفاده در کد)
label	string(100)	عنوان قابل نمایش
value	text	مقدار تنظیم
type	tinyInteger	نوع مقدار (بر اساس SettingType)
metadata	json	اطلاعات جانبی
description	string(512)	توضیحات (اختیاری)
updated_at	dateTime	زمان آخرین بروزرسانی
updated_by	foreignId	کاربر بروزرسانی‌کننده (nullable)

---

انواع تنظیمات (SettingType)

فیلد type مشخص می‌کند مقدار تنظیم چه نوع داده‌ای را در فیلد value قبول می‌کند.

مقدار	نام	کاربرد
1	TEXT	متن ساده
2	NUMBER	عدد
3	RADIO_GROUP	انتخاب تکی (رادیویی)
4	IMAGE	تصویر
5	FILE	فایل
6	SELECT	انتخاب تکی
7	MULTI_SELECT	انتخاب چندتایی
8	TEXTAREA	متن چندخطی
9	EDITOR	ویرایشگر پیشرفته
10	JSON	داده JSON

نکته

در تنظیمات IMAGE و FILE مقدار ذخیره شده در value شناسه فایل است.
در زمان دریافت مقدار با helperها، اطلاعات فایل در قالب File DTO (مطابق مستندات FileManager) برگردانده می‌شود.

نکته

در نوع JSON مقدار به صورت خودکار encode / decode می‌شود.
در نتیجه خروجی به شکل array در اختیار شما قرار می‌گیرد.

---

راه‌اندازی

پس از نصب پکیج، Seeder مربوط به Settings را اجرا کنید:

php artisan db:seed --class="Dornica\Foundation\Settings\Seeders\SettingSeeder"

---

اضافه کردن تنظیمات جدید

برای اضافه کردن تنظیمات جدید در پروژه، به صورت مستقیم در دیتابیس چیزی ایجاد نکنید.
تنظیمات باید از طریق Seeder به پروژه اضافه شوند تا در تمام محیط‌ها (local, staging, production) قابل تکرار باشند.

یک Seeder جدید بسازید:

php artisan make:seeder ProjectSettingsSeeder

سپس تنظیمات مورد نظر را اضافه کنید:

use Dornica\Foundation\Settings\Setting;
use Dornica\Foundation\Settings\Enums\SettingType;

Setting::updateOrCreate(
    ['code' => 'project_title'],
    [
        'label' => 'عنوان پروژه',
        'value' => 'My Project',
        'type'  => SettingType::TEXT,
    ]
);

در نهایت Seeder را در DatabaseSeeder ثبت کنید:

$this->call(ProjectSettingsSeeder::class);

---

استفاده در کد

روش پیشنهادی: Helper

setting(string $code, mixed $default = null): mixed

مثال

عنوان پروژه

$projectTitle = setting('project_title', 'پیش‌فرض');

حداقل طول رمز عبور

$minPassword = setting('min_password', 6);

مسیر لوگو

$logo = setting('logo');

---

استفاده از Facade

use Dornica\Foundation\Settings\Facade\Settings;

دریافت مقدار

$setting = Settings::get('project_name', 'my company');

اگر مقدار وجود نداشته باشد، مقدار پیش‌فرض برگردانده می‌شود.

---

ذخیره مقدار

Settings::set('project_name', 'company');

در صورتی که نوع تنظیم JSON باشد، آرایه ارسال شده به صورت خودکار به JSON تبدیل می‌شود.

Settings::set('more_setting', [
    "key" => "value"
]);

---

بررسی وجود تنظیم

if (Settings::has('logo')) {
    // exists
}

---

دریافت مقدار یا خطا

$logo = Settings::getOrFail('logo');

در صورت نبود تنظیم، یک Exception پرتاب می‌شود.

---

دسترسی مستقیم از طریق مدل

اگر به اطلاعات کامل تنظیم نیاز دارید:

use Dornica\Foundation\Settings\Setting;

$setting = Setting::whereCode('project_title')->first();

$value = $setting->value;
$label = $setting->label;
$metadata = $setting->metadata;

هشدار

استفاده مستقیم از مدل Setting توصیه نمی‌شود.
در این حالت منطق‌هایی مانند تبدیل نوع مقدار، پردازش فایل‌ها و مدیریت مقدار پیش‌فرض به صورت خودکار انجام نخواهد شد و باید به صورت دستی پیاده‌سازی شوند.

---

قوانین

یکتایی code

• مقدار code باید کاملاً یکتا باشد
• این مقدار در کد استفاده می‌شود
• تغییر آن ممکن است باعث شکستن بخش‌هایی از سیستم شود

---

جمع‌بندی

سیستم Settings یک لایه استاندارد برای مدیریت تنظیمات پروژه فراهم می‌کند:

• قابل استفاده در پنل و API
• قابل تغییر بدون دیپلوی
• پشتیبانی از انواع مختلف داده
• قابلیت Seeder و توسعه آسان

قاعده ساده است:

چیزی که ممکن است تغییر کند، در Settings قرار می‌گیرد. نه در env و نه در کد.