#System Settings

XinAdmin provides flexible system settings management with group management, custom form components, and auto-save functionality.

#Data Structure

#Setting Group (sys_setting_group)

#Setting Item (sys_setting_items)

#Supported Component Types

#Options Format

For Radio, Checkbox, and Select types, configure options like this:

value1=Option 1
value2=Option 2
value3=Option 3

Will be parsed as:

[
  { "label": "Option 1", "value": "value1" },
  { "label": "Option 2", "value": "value2" },
  { "label": "Option 3", "value": "value3" }
]

#Props Format

Add extra Ant Design props to components:

placeholder=Enter content
maxlength=100
disabled=false

Will be parsed as:

{
  "placeholder": "Enter content",
  "maxlength": 100,
  "disabled": false
}

#Frontend Usage

#Reading Settings

use Illuminate\Support\Facades\Cache;

// Get single setting
$siteName = setting('site.name');

// Get with default value
$siteName = setting('site.name', 'Default Site');

// Get entire group
$siteSettings = setting('site');

// Get all settings
$allSettings = setting();

#Using in Code

// Site name
$name = setting('site.name', 'XinAdmin');

// Check if feature is enabled
$enabled = setting('feature.enabled', false);

// Get dropdown options config
$options = setting('dropdown.options');

#API Reference

#Setting Groups

#Setting Items

#Get Items by Group

GET /api/admin/system/setting/item?group_id=1

#Save Setting Value

POST /api/admin/system/setting/item/{id}/value

Request Parameters:

Auto-save Mechanism:

Frontend triggers auto-save when user modifies settings, with 500ms debounce delay to avoid frequent requests.

#Usage Examples

#Creating a Site Settings Group

1. Create Group

{
  "title": "Site Settings",
  "key": "site",
  "remark": "Basic site information configuration"
}

2. Add Setting Items

Add site name setting:

{
  "key": "name",
  "title": "Site Name",
  "describe": "Site name displayed in browser tab",
  "type": "Input",
  "group_id": 1,
  "sort": 1
}

Add maintenance mode setting:

{
  "key": "maintenance",
  "title": "Enable Maintenance Mode",
  "describe": "When enabled, regular users cannot access",
  "type": "Switch",
  "group_id": 1,
  "sort": 2
}

Add date format setting:

{
  "key": "date_format",
  "title": "Date Format",
  "describe": "Select date display format",
  "type": "Select",
  "options": "Y-m-d=Year-Month-Day\nY/m/d=Year/Month/Day\nm-d-y=Month-Day-Year",
  "group_id": 1,
  "sort": 3
}

3. Using in Code

// Get site name
$siteName = setting('site.name', 'Default Site');

// Check maintenance mode
if (setting('site.maintenance', false)) {
    abort(503, 'Site is under maintenance...');
}

// Get date format
$dateFormat = setting('site.date_format', 'Y-m-d');

#Best Practices

#1. Group Planning

• Divide settings into functional modules
• Keep group keys unique and meaningful
• Add clear remarks for groups

#2. Naming Conventions

• Use dot-separated hierarchy: group.key
• Use lowercase letters and underscores for keys
• Ensure keys are unique across the system

#3. Security

• Sensitive configs (like API keys) should use encrypted storage
• Avoid hardcoding config values in client code
• Regularly clean up unused settings

#4. Performance

• Settings data is cached to reduce database queries
• Cache is automatically cleared after modification
• Consider database indexes for large settings