Settings
in package
Settings Class - A flexible configuration management system
This class provides a comprehensive solution for managing application settings organized into groups, with automatic file-based persistence using JSON format.
Key features:
- Group-based organization: Settings can be organized into logical groups
- Lazy loading: Data is loaded from files only when needed
- Memory caching: Once loaded, data remains in memory for performance
- Automatic persistence: Only modified groups are saved to disk
- Search functionality: Search by key names or values across groups
- Safe file handling: Group names are sanitized to prevent directory traversal
File structure:
- Each group is stored as a separate JSON file in the storage/ directory
- Files are named using the sanitized group name with .json extension
- Default group is stored as 'default.json'
Usage examples:
Basic operations: Settings::set('database_host', 'localhost'); $host = Settings::get('database_host');
Working with groups: Settings::set('smtp_server', 'mail.example.com', 'email'); $smtp = Settings::get('smtp_server', 'email');
Searching: $results = Settings::search_by_value('localhost'); $keys = Settings::search_by_key('database');
Persistence: Settings::save(); // Saves all modified groups to disk
Table of Contents
Methods
- clear_group() : void
- Completely empties a group
- get() : mixed|null
- Gets a value from the specified group
- get_all() : array<string, mixed>
- Gets all data from a group
- has_key() : bool
- Checks if a key exists in a group
- remove_key() : void
- Removes a key from a group
- save() : void
- Saves all groups marked as modified to their respective JSON files
- search_by_key() : array<string, array<string, mixed>>
- Searches for a specific key in a group or all groups
- search_by_value() : array<string, array<string, mixed>>
- Searches for a value in a specific group or all groups
- set() : void
- Sets a value in the specified group
Methods
clear_group()
Completely empties a group
public
static clear_group([string|null $group = null ]) : void
Removes all settings from the specified group, effectively resetting it to an empty state. If the group is not specified, clears the default group. Marks the group as modified for persistence.
Examples:
- Settings::clear_group() → clears default group
- Settings::clear_group('cache') → clears all cache settings
- Settings::clear_group('temp') → removes all temporary settings
Parameters
- $group : string|null = null
-
The group name (uses default if null)
get()
Gets a value from the specified group
public
static get(string $key[, string|null $group = null ]) : mixed|null
Retrieves a setting value by key from a specific group. If the group is not specified, uses the default group. Returns null if the key doesn't exist.
Examples:
- Settings::get('app_name') → 'My Application' (from default group)
- Settings::get('smtp_host', 'email') → 'smtp.gmail.com' (from email group)
- Settings::get('nonexistent') → null (key doesn't exist)
Parameters
- $key : string
-
The setting key to retrieve
- $group : string|null = null
-
The group name (uses default if null)
Return values
mixed|null —The setting value or null if not found
get_all()
Gets all data from a group
public
static get_all([string|null $group = null ]) : array<string, mixed>
Returns all key-value pairs from the specified group as an associative array. If the group is not specified, uses the default group. Returns an empty array if the group has no data.
Examples:
- Settings::get_all() → ['app_name' => 'My App', 'version' => '1.0']
- Settings::get_all('email') → ['smtp_host' => 'smtp.gmail.com', 'port' => 587]
- Settings::get_all('nonexistent') → []
Parameters
- $group : string|null = null
-
The group name (uses default if null)
Return values
array<string, mixed> —All key-value pairs from the group
has_key()
Checks if a key exists in a group
public
static has_key(string $key[, string|null $group = null ]) : bool
Verifies whether a specific setting key exists in the given group. If the group is not specified, checks in the default group. Useful for conditional logic before getting or setting values.
Examples:
- Settings::has_key('app_name') → true if exists in default group
- Settings::has_key('smtp_host', 'email') → true if exists in email group
- Settings::has_key('nonexistent') → false
Parameters
- $key : string
-
The key to check for
- $group : string|null = null
-
The group name (uses default if null)
Return values
bool —True if the key exists, false otherwise
remove_key()
Removes a key from a group
public
static remove_key(string $key[, string|null $group = null ]) : void
Deletes a specific setting key and its value from the specified group. If the group is not specified, uses the default group. Marks the group as modified if the key existed.
Examples:
- Settings::remove_key('old_setting') → removes from default group
- Settings::remove_key('temp_config', 'cache') → removes from cache group
- Settings::remove_key('nonexistent') → no effect, doesn't error
Parameters
- $key : string
-
The key to remove
- $group : string|null = null
-
The group name (uses default if null)
save()
Saves all groups marked as modified to their respective JSON files
public
static save() : void
This method implements efficient persistence by only saving groups that have been modified since the last save. It creates the storage directory if it doesn't exist and writes JSON files with pretty formatting and Unicode support.
After successful saving, the modified flags are cleared to prevent unnecessary future saves until the data changes again.
JSON formatting options:
- JSON_PRETTY_PRINT: Makes files human-readable
- JSON_UNESCAPED_UNICODE: Preserves Unicode characters
Examples:
- After Settings::set('key', 'value'), call Settings::save() to persist
- Typically called at the end of request processing
- Can be called multiple times safely (only saves what's modified)
search_by_key()
Searches for a specific key in a group or all groups
public
static search_by_key(string $search_key[, string|null $group = null ]) : array<string, array<string, mixed>>
Performs a case-insensitive substring search on setting keys. Can search within a specific group or across all available groups. Useful for finding related settings or discovering available configuration options.
Examples:
- Settings::search_by_key('database') → finds 'database_host', 'database_port', etc.
- Settings::search_by_key('smtp', 'email') → finds SMTP-related keys in email group
- Settings::search_by_key('_timeout') → finds all timeout-related settings
Return format: [ 'group_name' => [ 'matching_key' => 'value', ... ], ... ]
Parameters
- $search_key : string
-
The key pattern to search for
- $group : string|null = null
-
The group to search in (searches all if null)
Return values
array<string, array<string, mixed>> —Search results organized by group
search_by_value()
Searches for a value in a specific group or all groups
public
static search_by_value(mixed $search_value[, string|null $group = null ]) : array<string, array<string, mixed>>
Performs a case-insensitive search for the given value across settings. Can search within a specific group or across all available groups. Handles different data types: strings (substring match), arrays (recursive search), and numbers (exact match).
When searching all groups, it loads all available JSON files from storage.
Examples:
- Settings::search_by_value('gmail') → finds all settings containing 'gmail'
- Settings::search_by_value('localhost', 'database') → searches only in database group
- Settings::search_by_value(587) → finds exact numeric matches
Return format: [ 'group_name' => [ 'setting_key' => 'setting_value', ... ], ... ]
Parameters
- $search_value : mixed
-
The value to search for
- $group : string|null = null
-
The group to search in (searches all if null)
Return values
array<string, array<string, mixed>> —Search results organized by group
set()
Sets a value in the specified group
public
static set(string $key, mixed $value[, string|null $group = null ]) : void
Stores a setting value with the given key in the specified group. If the group is not specified, uses the default group. Marks the group as modified for later persistence.
Examples:
- Settings::set('app_name', 'My App') → stores in default group
- Settings::set('smtp_port', 587, 'email') → stores in email group
- Settings::set('config', ['key' => 'value']) → stores array
- Settings::set('enabled', true) → stores boolean
Parameters
- $key : string
-
The setting key
- $value : mixed
-
The setting value (can be any JSON-serializable type)
- $group : string|null = null
-
The group name (uses default if null)