Milk Admin

Settings Class Documentation

Description

The Settings class provides a comprehensive system for managing application configurations organized by groups, with automatic file persistence using JSON format.

Main features:

  • Organization by logical groups
  • Lazy loading (only when needed)
  • In-memory cache for performance
  • Automatic persistence of modified data
  • Advanced search functionality

Main Public Methods

set($key, $value, $group = null)

Sets a value in the specified group.

public static function set(string $key, mixed $value, ?string $group = null): void

Parameters:

  • $key - String - The setting key.
  • $value - mixed - The value to store (any JSON-serializable type).
  • $group - String (optional) - The group name (uses 'default' if null).

Examples:

// Save in default group
Settings::set('app_name', 'My Application');

// Save in 'email' group
Settings::set('smtp_host', 'smtp.gmail.com', 'email');

// Save arrays or objects
Settings::set('database_config', ['host' => 'localhost', 'port' => 3306]);

get($key, $group = null)

Retrieves a value from the specified group.

public static function get(string $key, ?string $group = null): mixed

Parameters:

  • $key - String - The setting key to retrieve.
  • $group - String (optional) - The group name (uses 'default' if null).

Returns: mixed|null - The setting value or null if not found.

Examples:

// Retrieve from default group
$app_name = Settings::get('app_name');

// Retrieve from 'email' group
$smtp_host = Settings::get('smtp_host', 'email');

// Handle non-existent value
$setting = Settings::get('nonexistent') ?? 'default_value';

getAll($group = null)

Retrieves all data from a group as an associative array.

public static function getAll(?string $group = null): array

Parameters:

  • $group - String (optional) - The group name (uses 'default' if null).

Returns: Array - All key-value pairs from the group.

Examples:

// Retrieve all settings from default group
$default_settings = Settings::getAll();

// Retrieve all email settings
$email_config = Settings::getAll('email');

hasKey($key, $group = null)

Checks if a key exists in the specified group.

public static function hasKey(string $key, ?string $group = null): bool

Parameters:

  • $key - String - The key to check.
  • $group - String (optional) - The group name (uses 'default' if null).

Returns: Boolean - true if the key exists, false otherwise.

Examples:

// Check existence in default group
if (Settings::hasKey('app_name')) {
    echo "App name is configured";
}

// Check existence in a specific group
if (Settings::hasKey('smtp_host', 'email')) {
    $host = Settings::get('smtp_host', 'email');
}

save()

Saves all modified groups to their respective JSON files.

public static function save(): void

This method implements efficient persistence by saving only groups that have been modified since the last save.

Saving is handled automatically at the end of code execution, so there is no need to rewrite it

Examples:

// Set some configurations
Settings::set('app_name', 'My App');
Settings::set('smtp_host', 'smtp.gmail.com', 'email');

// Save all changes to files
Settings::save();

Search Methods

searchByValue($search_value, $group = null)

Searches for a value in a specific group or all groups.

public static function searchByValue(mixed $search_value, ?string $group = null): array

Parameters:

  • $search_value - mixed - The value to search for.
  • $group - String (optional) - The group to search in (searches all if null).

Returns: Array - Results organized by group.

Examples:

// Search for 'gmail' in all groups
$results = Settings::searchByValue('gmail');

// Search only in 'email' group
$email_results = Settings::searchByValue('localhost', 'email');

searchByKey($search_key, $group = null)

Searches for keys that contain a specific string.

public static function searchByKey(string $search_key, ?string $group = null): array

Parameters:

  • $search_key - String - The string to search for in keys.
  • $group - String (optional) - The group to search in (searches all if null).

Returns: Array - Results organized by group.

Examples:

// Find all keys containing 'database'
$db_settings = Settings::searchByKey('database');

// Find SMTP keys in email group
$smtp_settings = Settings::searchByKey('smtp', 'email');

Management Methods

removeKey($key, $group = null)

Removes a key from a group.

public static function removeKey(string $key, ?string $group = null): void

Parameters:

  • $key - String - The key to remove.
  • $group - String (optional) - The group name (uses 'default' if null).

Examples:

// Remove from default group
Settings::removeKey('old_setting');

// Remove from specific group
Settings::removeKey('temp_config', 'cache');

clearGroup($group = null)

Completely empties a group by removing all settings.

public static function clearGroup(?string $group = null): void

Parameters:

  • $group - String (optional) - The group name (uses 'default' if null).

Examples:

// Clear default group
Settings::clearGroup();

// Clear cache group
Settings::clearGroup('cache');

Complete Usage Example

// Application configuration
Settings::set('app_name', 'My CMS');
Settings::set('app_version', '1.0.0');
Settings::set('debug_mode', true);

// Email configuration
Settings::set('smtp_host', 'smtp.gmail.com', 'email');
Settings::set('smtp_port', 587, 'email');
Settings::set('smtp_username', 'user@example.com', 'email');

// Database configuration
Settings::set('host', 'localhost', 'database');
Settings::set('port', 3306, 'database');
Settings::set('charset', 'utf8mb4', 'database');

// Retrieving configurations
$app_name = Settings::get('app_name');
$email_config = Settings::getAll('email');
$db_host = Settings::get('host', 'database');

// Check existence
if (Settings::hasKey('debug_mode')) {
    $debug = Settings::get('debug_mode');
}

// Search
$smtp_settings = Settings::searchByKey('smtp', 'email');
$localhost_configs = Settings::searchByValue('localhost');

// Save changes
Settings::save();

Important Notes:

  • Configuration files are saved in the storage/ directory as JSON files
  • Each group is saved in a separate file (e.g., email.json, database.json)
  • Loading is lazy: data is loaded only when needed
  • In-memory cache improves performance for repeated accesses
  • Only modified groups are saved to disk
  • Group names are sanitized to prevent directory traversal attacks