Config
in package
Handles loading and saving SMF's settings, both in Settings.php and database.
Handles checking and modifying certain server and forum configuration values.
Table of Contents
Properties
- $backward_compatibility : int
- $boarddir : string
- $boardurl : string
- $cache_accelerator : string
- $cache_enable : int
- $cache_memcached : string
- $cachedir : string
- $cachedir_sqlite : string
- $cookiename : string
- $custom : array<string|int, mixed>
- $db_character_set : string
- $db_error_send : bool
- $db_last_error : int
- $db_mb4 : null|bool
- $db_name : string
- $db_passwd : string
- $db_persist : bool
- $db_port : int
- $db_prefix : string
- $db_server : string
- $db_show_debug : bool
- $db_type : string
- $db_user : string
- $image_proxy_enabled : bool
- $image_proxy_maxsize : int
- $image_proxy_secret : string
- $language : string
- $languagesdir : string
- Path to the Packages directory.
- $maintenance : int
- $mbname : string
- $mmessage : string
- Description of why the forum is in maintenance mode.
- $modSettings : array<string|int, mixed>
- $mtitle : string
- $packagesdir : string
- Path to the Packages directory.
- $scripturl : string
- $sourcedir : string
- $ssi_db_passwd : string
- $ssi_db_user : string
- $webmaster_email : string
- $auth_secret : string|null
- $exported : bool
- $settings_defs : array<string|int, mixed>
- $temp_dir : string
Methods
- checkCron() : void
- Ensures SMF's scheduled tasks are being run as intended
- generateSeed() : void
- Generate a random seed and ensure it's stored in settings.
- getAuthSecret() : string
- Gets, and if necessary creates, the authentication secret to use for cookies, tokens, etc.
- getCurrentSettings() : array<string|int, mixed>|bool
- Retrieves a copy of the current values of all settings in Settings.php.
- getDbLastError() : int
- Sets Config::$db_last_error to the timestamp of the last recorded database error for the error log, and also returns that timestamp.
- getSettingsDefs() : array<string|int, mixed>
- Describes properties of all known Settings.php variables and other content.
- getTempDir() : string
- Locates the most appropriate temporary directory.
- load() : void
- Loads properties directly from Settings.php.
- reloadModSettings() : void
- Load the Config::$modSettings array.
- safeFileWrite() : bool
- Writes data to a file, optionally making a backup, while avoiding race conditions.
- set() : void
- Sets the properties of this class to the specified values.
- stripPhpComments() : string
- Deletes all PHP comments from a string.
- updateDbLastError() : bool
- Saves the time of the last database error for the error log.
- updateModSettings() : void
- Updates the settings table as well as Config::$modSettings... - Updates both the settings table and Config::$modSettings array.
- updateSettingsFile() : bool
- Update the Settings.php file.
- varExport() : string
- A wrapper around var_export() that enhances it for SMF's purposes:
Properties
$backward_compatibility
public
static int
$backward_compatibility
Master switch to enable backward compatibility behaviours: 0: Off. This is the default. 1: On. This will be set automatically if an installed modification needs it. 2: Forced on. Use this to enable backward compatibility behaviours even when no installed modifications require them. This is usually not necessary.
$boarddir
public
static string
$boarddir
The absolute path to the forum's folder. (not just '.'!)
$boardurl
public
static string
$boardurl
URL to your forum's folder. (without the trailing /!)
$cache_accelerator
public
static string
$cache_accelerator
Select a cache system. You should leave this up to the cache area of the admin panel for proper detection of the available options.
$cache_enable
public
static int
$cache_enable
The level at which you would like to cache. Between 0 (off) through 3 (cache a lot).
$cache_memcached
public
static string
$cache_memcached
This is only used for the memcache / memcached cache systems. Should be a string of 'server:port,server:port'
$cachedir
public
static string
$cachedir
Path to the cache directory for the file-based cache system.
$cachedir_sqlite
public
static string
$cachedir_sqlite
This is only used for the SQLite3 cache system. Path to the directory where the SQLite3 database file will be saved.
$cookiename
public
static string
$cookiename
Name of the cookie to set for authentication.
$custom
public
static array<string|int, mixed>
$custom
= []
Holds any custom settings found in Settings.php.
$db_character_set
public
static string
$db_character_set
Database character set. Should always be utf8.
$db_error_send
public
static bool
$db_error_send
Send emails on database connection error.
$db_last_error
public
static int
$db_last_error
Last database error.
$db_mb4
public
static null|bool
$db_mb4
Override the default behavior of the database layer for mb4 handling. null keep the default behavior untouched.
$db_name
public
static string
$db_name
The database name.
$db_passwd
public
static string
$db_passwd
Database password.
$db_persist
public
static bool
$db_persist
Use a persistent database connection.
$db_port
public
static int
$db_port
The database port. 0 to use default port for the database type.
$db_prefix
public
static string
$db_prefix
A prefix to put in front of your table names. This helps to prevent conflicts.
$db_server
public
static string
$db_server
The server to connect to (or a Unix socket)
$db_show_debug
public
static bool
$db_show_debug
Whether to show debug info.
$db_type
public
static string
$db_type
The database type. Default options: mysql, postgresql
$db_user
public
static string
$db_user
Database username.
$image_proxy_enabled
public
static bool
$image_proxy_enabled
Whether the proxy is enabled or not.
$image_proxy_maxsize
public
static int
$image_proxy_maxsize
Maximum file size (in KB) for individual files.
$image_proxy_secret
public
static string
$image_proxy_secret
Secret key to be used by the proxy.
$language
public
static string
$language
The default language file set for the forum.
$languagesdir
Path to the Packages directory.
public
static string
$languagesdir
$maintenance
public
static int
$maintenance
0, 1, 2
The maintenance "mode": 0: Disable maintenance mode. This is the default. 1: Enable maintenance mode but allow admins to login normally. 2: Make the forum untouchable. You'll need to make it 0 again manually!
$mbname
public
static string
$mbname
The name of your forum.
$mmessage
Description of why the forum is in maintenance mode.
public
static string
$mmessage
$modSettings
public
static array<string|int, mixed>
$modSettings
= []
Holds settings loaded from the settings table in the database.
$mtitle
public
static string
$mtitle
Title for the maintenance mode message.
$packagesdir
Path to the Packages directory.
public
static string
$packagesdir
$scripturl
public
static string
$scripturl
URL of SMF's main index.php.
$sourcedir
public
static string
$sourcedir
Path to the Sources directory.
$ssi_db_passwd
public
static string
$ssi_db_passwd
Database password for when connecting with SSI.
$ssi_db_user
public
static string
$ssi_db_user
Database user for when connecting with SSI.
$webmaster_email
public
static string
$webmaster_email
Email address to send emails from. (like noreply@yourdomain.com.)
$auth_secret
protected
static string|null
$auth_secret
Authentication secret. This is protected in order to force access via Config::getAuthSecret()
$exported
protected
static bool
$exported
= false
Tracks whether static variables and functions have been exported to global namespace.
$settings_defs
protected
static array<string|int, mixed>
$settings_defs
= [
['text' => "\n" . '/**' . "\n" . ' * The settings file contains all of the basic settings that need to be present when a database/cache is not available.' . "\n" . ' *' . "\n" . ' * Simple Machines Forum (SMF)' . "\n" . ' *' . "\n" . ' * @package SMF' . "\n" . ' * @author Simple Machines https://www.simplemachines.org' . "\n" . ' * @copyright ' . SMF_SOFTWARE_YEAR . ' Simple Machines and individual contributors' . "\n" . ' * @license https://www.simplemachines.org/about/smf/license.php BSD' . "\n" . ' *' . "\n" . ' * @version ' . SMF_VERSION . "\n" . ' */' . "\n" . '', 'search_pattern' => '~/\*\*.*?@package\h+SMF\b.*?\*/\n{0,2}~s'],
'maintenance' => ['text' => <<<'END'
########## Maintenance ##########
/**
* @var int 0, 1, 2
*
* The maintenance "mode":
* 0: Disable maintenance mode. This is the default.
* 1: Enable maintenance mode but allow admins to login normally.
* 2: Make the forum untouchable. You'll need to make it 0 again manually!
*/
END, 'default' => 0, 'type' => 'integer'],
'mtitle' => ['text' => <<<'END'
/**
* @var string
*
* Title for the Maintenance Mode message.
*/
END, 'default' => 'Maintenance Mode', 'type' => 'string'],
'mmessage' => ['text' => <<<'END'
/**
* @var string
*
* Description of why the forum is in maintenance mode.
*/
END, 'default' => 'Okay faithful users...we\'re attempting to restore an older backup of the database...news will be posted once we\'re back!', 'type' => 'string'],
'mbname' => ['text' => <<<'END'
########## Forum Info ##########
/**
* @var string
*
* The name of your forum.
*/
END, 'default' => 'My Community', 'type' => 'string'],
'language' => ['text' => <<<'END'
/**
* @var string
*
* The default language file set for the forum.
*/
END, 'default' => 'en_US', 'type' => 'string'],
'boardurl' => ['text' => <<<'END'
/**
* @var string
*
* URL to your forum's folder. (without the trailing /!)
*/
END, 'default' => 'http://127.0.0.1/smf', 'type' => 'string'],
'webmaster_email' => ['text' => <<<'END'
/**
* @var string
*
* Email address to send emails from. (like noreply@yourdomain.com.)
*/
END, 'default' => 'noreply@myserver.com', 'type' => 'string'],
'cookiename' => ['text' => <<<'END'
/**
* @var string
*
* Name of the cookie to set for authentication.
*/
END, 'default' => 'SMFCookie11', 'type' => 'string'],
'auth_secret' => ['text' => <<<'END'
/**
* @var string
*
* Secret key used to create and verify cookies, tokens, etc.
* Do not change this unless absolutely necessary, and NEVER share it.
*
* Note: Changing this will immediately log out all members of your forum
* and break the token-based links in all previous email notifications,
* among other possible effects.
*/
END, 'default' => null, 'auto_delete' => 1, 'type' => 'string'],
'db_type' => ['text' => <<<'END'
########## Database Info ##########
/**
* @var string
*
* The database type.
* Default options: mysql, postgresql
*/
END, 'default' => 'mysql', 'type' => 'string'],
'db_port' => ['text' => <<<'END'
/**
* @var int
*
* The database port.
* 0 to use default port for the database type.
*/
END, 'default' => 0, 'type' => 'integer'],
'db_server' => ['text' => <<<'END'
/**
* @var string
*
* The server to connect to (or a Unix socket)
*/
END, 'default' => 'localhost', 'required' => true, 'type' => 'string'],
'db_name' => ['text' => <<<'END'
/**
* @var string
*
* The database name.
*/
END, 'default' => 'smf', 'required' => true, 'type' => 'string'],
'db_user' => ['text' => <<<'END'
/**
* @var string
*
* Database username.
*/
END, 'default' => 'root', 'required' => true, 'type' => 'string'],
'db_passwd' => ['text' => <<<'END'
/**
* @var string
*
* Database password.
*/
END, 'default' => '', 'required' => true, 'type' => 'string', 'is_password' => true],
'ssi_db_user' => ['text' => <<<'END'
/**
* @var string
*
* Database user for when connecting with SSI.
*/
END, 'default' => '', 'type' => 'string'],
'ssi_db_passwd' => ['text' => <<<'END'
/**
* @var string
*
* Database password for when connecting with SSI.
*/
END, 'default' => '', 'type' => 'string', 'is_password' => true],
'db_prefix' => ['text' => <<<'END'
/**
* @var string
*
* A prefix to put in front of your table names.
* This helps to prevent conflicts.
*/
END, 'default' => 'smf_', 'required' => true, 'type' => 'string'],
'db_persist' => ['text' => <<<'END'
/**
* @var bool
*
* Use a persistent database connection.
*/
END, 'default' => false, 'type' => 'boolean'],
'db_error_send' => ['text' => <<<'END'
/**
* @var bool
*
* Send emails on database connection error.
*/
END, 'default' => false, 'type' => 'boolean'],
'db_mb4' => ['text' => <<<'END'
/**
* @var null|bool
*
* Override the default behavior of the database layer for mb4 handling.
* null keep the default behavior untouched.
*/
END, 'default' => null, 'type' => ['NULL', 'boolean']],
'cache_accelerator' => ['text' => <<<'END'
########## Cache Info ##########
/**
* @var string
*
* Select a cache system. You should leave this up to the cache area of the
* admin panel for proper detection of the available options.
*/
END, 'default' => '', 'type' => 'string'],
'cache_enable' => ['text' => <<<'END'
/**
* @var int
*
* The level at which you would like to cache.
* Between 0 (off) through 3 (cache a lot).
*/
END, 'default' => 0, 'type' => 'integer'],
'cache_memcached' => ['text' => <<<'END'
/**
* @var array
*
* This is only used for memcache / memcached.
* Should be a string of 'server:port,server:port'
*/
END, 'default' => '', 'type' => 'string'],
'cachedir' => ['text' => <<<'END'
/**
* @var string
*
* Path to the cache directory for the file-based cache system.
*/
END, 'default' => '__DIR__ . \'/cache\'', 'raw_default' => true, 'type' => 'string'],
'cachedir_sqlite' => ['text' => <<<'END'
/**
* @var string
*
* This is only used for the SQLite3 cache system.
* Path to the directory where the SQLite3 database file will be saved.
*/
END, 'default' => '', 'auto_delete' => 2, 'type' => 'string'],
'image_proxy_enabled' => ['text' => <<<'END'
########## Image Proxy ##########
/**
* @var bool
*
* Whether the proxy is enabled or not.
*/
END, 'default' => true, 'type' => 'boolean'],
'image_proxy_secret' => ['text' => <<<'END'
/**
* @var string
*
* Secret key to be used by the proxy.
*/
END, 'default' => 'smfisawesome', 'type' => 'string'],
'image_proxy_maxsize' => ['text' => <<<'END'
/**
* @var int
*
* Maximum file size (in KB) for individual files.
*/
END, 'default' => 5192, 'type' => 'integer'],
'boarddir' => ['text' => <<<'END'
########## Directories/Files ##########
# Note: These directories do not have to be changed unless you move things.
/**
* @var string
*
* The absolute path to the forum's folder. (not just '.'!)
*/
END, 'default' => '__DIR__', 'raw_default' => true, 'type' => 'string'],
'sourcedir' => ['text' => <<<'END'
/**
* @var string
*
* Path to the Sources directory.
*/
END, 'default' => '__DIR__ . \'/Sources\'', 'raw_default' => true, 'type' => 'string'],
'packagesdir' => ['text' => <<<'END'
/**
* @var string
*
* Path to the Packages directory.
*/
END, 'default' => '__DIR__ . \'/Packages\'', 'raw_default' => true, 'type' => 'string'],
'languagesdir' => ['text' => <<<'END'
/**
* @var string
*
* Path to the Languages directory.
*/
END, 'default' => '__DIR__ . \'/Languages\'', 'raw_default' => true, 'type' => 'string'],
'backward_compatibility' => ['text' => <<<'END'
######### Modification Support #########
/**
* @var int
*
* Master switch to enable backward compatibility behaviours:
* 0: Off. This is the default.
* 1: On. This will be set automatically if an installed modification needs it.
* 2: Forced on. Use this to enable backward compatibility behaviours even when
* no installed modifications require them. This is usually not necessary.
*/
END, 'default' => 0, 'type' => 'integer'],
'db_character_set' => ['text' => <<<'END'
######### Legacy Settings #########
/**
* @var string
*
* Database character set. Should always be utf8.
*/
END, 'default' => 'utf8', 'type' => 'string'],
'db_show_debug' => ['text' => <<<'END'
######### Developer Settings #########
/**
* @var bool
*
* Whether to show debug info.
*/
END, 'default' => false, 'auto_delete' => 2, 'type' => 'boolean'],
// Temporary variable used during the upgrade process.
'upgradeData' => ['default' => '', 'auto_delete' => 1, 'type' => 'string'],
// These should be removed if found.
'tasksdir' => ['default' => '', 'auto_delete' => 3, 'type' => 'string'],
'db_last_error' => ['default' => 0, 'auto_delete' => 3, 'type' => 'integer'],
]
A big, fat array to define properties of all the Settings.php variables and other content like code blocks.
-
String keys are used to identify actual variables.
-
Integer keys are used for content not connected to any particular variable, such as code blocks or the license block.
-
The content of the 'text' element is simply printed out, if it is used at all. Use it for comments or to insert code blocks, etc.
-
The 'default' element, not surprisingly, gives a default value for the variable.
-
The 'type' element defines the expected variable type or types. If more than one type is allowed, this should be an array listing them. Types should match the possible types returned by gettype().
-
If 'raw_default' is true, the default should be printed directly, rather than being handled as a string. Use it if the default contains code, e.g. 'dirname(FILE)'
-
If 'required' is true and a value for the variable is undefined, the update will be aborted. (The only exception is during the SMF installation process.)
-
The 'auto_delete' property can have one of the following values:
- 0: The variable will never be deleted.
- 1: If the variable is empty, it will be deleted.
- 2: Behaviour depends on $rebuild: if $rebuild is true, 'auto_delete' == 2 behaves like 'auto_delete' == 1; if $rebuild is false, 'auto_delete' == 2 behaves like 'auto_delete' == 0.
- 3: The variable will always be deleted, even if it is not empty. This is used to remove obsolete variables.
-
The 'is_password' element indicates that a value is a password. This is used primarily to tell SMF how to interpret input when the value is being set to a new value.
-
The optional 'search_pattern' element defines a custom regular expression to search for the existing entry in the file. This is primarily useful for code blocks rather than variables.
-
The optional 'replace_pattern' element defines a custom regular expression to decide where the replacement entry should be inserted. Note: 'replace_pattern' should be avoided unless ABSOLUTELY necessary.
$temp_dir
protected
static string
$temp_dir
Path to a temporary directory.
Methods
checkCron()
Ensures SMF's scheduled tasks are being run as intended
public
static checkCron() : void
If the admin activated the cron_is_real_cron setting, but the cron job is not running things at least once per day, we need to go back to SMF's default behaviour using "web cron" JavaScript calls.
generateSeed()
Generate a random seed and ensure it's stored in settings.
public
static generateSeed() : void
This only exists for backward compatibility with mods that might use the generated value.
getAuthSecret()
Gets, and if necessary creates, the authentication secret to use for cookies, tokens, etc.
public
static getAuthSecret() : string
Return values
string —The authentication secret.
getCurrentSettings()
Retrieves a copy of the current values of all settings in Settings.php.
public
static getCurrentSettings([int|float $mtime = null ][, string $settingsFile = SMF_SETTINGS_FILE ]) : array<string|int, mixed>|bool
Importantly, it does this without affecting our working settings at all, and it performs safety checks before acting. The result is an array of the values as recorded in the settings file.
Parameters
- $mtime : int|float = null
-
Timestamp of last known good configuration. Defaults to time SMF started.
- $settingsFile : string = SMF_SETTINGS_FILE
-
The settings file. Defaults to SMF's standard Settings.php.
Return values
array<string|int, mixed>|bool —An array of name/value pairs for all settings in the file, or false on error.
getDbLastError()
Sets Config::$db_last_error to the timestamp of the last recorded database error for the error log, and also returns that timestamp.
public
static getDbLastError() : int
Return values
int —Timestamp of the last database error.
getSettingsDefs()
Describes properties of all known Settings.php variables and other content.
public
static getSettingsDefs() : array<string|int, mixed>
Helper for updateSettingsFile(); also called by saveSettings().
Return values
array<string|int, mixed> —Descriptions of all known Settings.php content.
getTempDir()
Locates the most appropriate temporary directory.
public
static getTempDir() : string
Systems using open_basedir
restrictions may receive errors with
sys_get_temp_dir()
due to misconfigurations on servers. Other
cases sys_temp_dir may not be set to a safe value. Additionally
sys_get_temp_dir
may use a readonly directory. This attempts to
find a working temp directory that is accessible under the
restrictions and is writable to the web service account.
Directories checked against open_basedir
:
sys_get_temp_dir()
upload_tmp_dir
session.save_path
cachedir
Return values
string —Path to a temporary directory.
load()
Loads properties directly from Settings.php.
public
static load() : void
reloadModSettings()
Load the Config::$modSettings array.
public
static reloadModSettings() : void
safeFileWrite()
Writes data to a file, optionally making a backup, while avoiding race conditions.
public
static safeFileWrite(string $file, string $data[, string|null $backup_file = null ][, int|null $mtime = null ][, bool $append = false ]) : bool
Parameters
- $file : string
-
The filepath of the file where the data should be written.
- $data : string
-
The data to be written to $file.
- $backup_file : string|null = null
-
Path where the backup should be saved. Default null.
- $mtime : int|null = null
-
If modification time of $file is more recent than this Unix timestamp, the write operation will abort. Defaults to time that the script started execution.
- $append : bool = false
-
If true, the data will be appended instead of overwriting the existing content of the file. Default false.
Return values
bool —Whether the write operation succeeded or not.
set()
Sets the properties of this class to the specified values.
public
static set(array<string|int, mixed> $settings) : void
Parameters
- $settings : array<string|int, mixed>
-
The settings values to use.
stripPhpComments()
Deletes all PHP comments from a string.
public
static stripPhpComments(string $code_str) : string
Parameters
- $code_str : string
-
A string containing PHP code.
Return values
string —A string of PHP code with no comments in it.
updateDbLastError()
Saves the time of the last database error for the error log.
public
static updateDbLastError(int $time) : bool
Done separately from updateSettingsFile to avoid race conditions that can occur during a database error.
Parameters
- $time : int
-
The timestamp of the last database error.
Return values
bool —Whether we could successfully put the file or not.
updateModSettings()
Updates the settings table as well as Config::$modSettings... - Updates both the settings table and Config::$modSettings array.
public
static updateModSettings(array<string|int, mixed> $change_array[, bool $update = false ]) : void
- All of change_array's indexes and values are assumed to have escaped apostrophes.
- If a variable is already set to what you want to change it to, that variable will be skipped over; it would be unnecessary to reset.
- When $update is true, UPDATEs will be used instead of REPLACE.
- When $update is true, the value can be true or false to increment or decrement it, respectively.
- Only does one at a time if $update is true.
Parameters
- $change_array : array<string|int, mixed>
-
An array of info about what we're changing in 'setting' => 'value' format.
- $update : bool = false
-
Whether to use an UPDATE query instead of a REPLACE query.
updateSettingsFile()
Update the Settings.php file.
public
static updateSettingsFile(array<string|int, mixed> $config_vars[, bool|null $keep_quotes = null ][, bool $rebuild = false ]) : bool
MOD AUTHORS: If you add a setting to Settings.php, you should use the integrate_update_settings_file hook to define it in getSettingsDefs().
-
Updates the Settings.php file with the changes supplied in config_vars.
-
Expects config_vars to be an associative array, with the keys as the variable names in Settings.php, and the values the variable values.
-
Correctly formats the values using self::varExport().
-
Restores standard formatting of the file, if $rebuild is true.
-
Checks for changes to db_last_error and passes those off to a separate handler.
-
Creates a backup file and will use it should the writing of the new settings file fail.
-
Tries to intelligently trim quotes and remove slashes from string values. This is done for backwards compatibility purposes (old versions of this function expected strings to have been manually escaped and quoted). This behaviour can be controlled by the $keep_quotes param.
Parameters
- $config_vars : array<string|int, mixed>
-
An array of one or more variables to update.
- $keep_quotes : bool|null = null
-
Whether to strip slashes and trim quotes from string values. Defaults to auto-detection.
- $rebuild : bool = false
-
If true, attempts to rebuild with standard format. Default false.
Return values
bool —True on success, false on failure.
varExport()
A wrapper around var_export() that enhances it for SMF's purposes:
public
static varExport(mixed $var) : string
-
Produces output that matches SMF's coding standard.
-
Converts raw line breaks and tabs in strings to PHP escaped characters (i.e. "\r", "\n" and "\t"), which makes some things easier elsewhere.
-
Exports objects that do not implement the __set_state() method in a way that will nevertheless allow them to be re-imported successfully.
Parameters
- $var : mixed
-
The variable to export.
Return values
string —A PHP-parseable representation of the variable's value.