Documentation

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
  1. Produces output that matches SMF's coding standard.

  2. Converts raw line breaks and tabs in strings to PHP escaped characters (i.e. "\r", "\n" and "\t"), which makes some things easier elsewhere.

  3. 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.


        
On this page

Search results