symphony/lib/core/class.configuration.php
<?php
/**
* @package core
*/
/**
* The Configuration class acts as a property => value store for settings
* used throughout Symphony. The result of this class is a string containing
* a PHP representation of the properties (and their values) set by the Configuration.
* Symphony's configuration file is saved at `CONFIG`. The initial
* file is generated by the Symphony installer, and then subsequent use of Symphony
* loads in this file for each page view. Like minded properties can be grouped.
*/
class Configuration
{
/**
* An associative array of the properties for this Configuration object
* @var array
*/
private $_properties = array();
/**
* Whether all properties and group keys will be forced to be lowercase.
* By default this is false, which makes all properties case sensitive
* @var boolean
*/
private $_forceLowerCase = false;
/**
* The constructor for the Configuration class takes one parameter,
* `$forceLowerCase` which will make all property and
* group names lowercase or not. By default they are left to the case
* the user provides
*
* @param boolean $forceLowerCase
* False by default, if true this will make all property and group names
* lowercase
*/
public function __construct($forceLowerCase = false)
{
$this->_forceLowerCase = $forceLowerCase;
}
/**
* Setter for the `$this->_properties`. The properties array
* can be grouped to be an 'array' of an 'array' of properties. For instance
* a 'region' key may be an array of 'properties' (that is name/value), or it
* may be a 'value' itself.
*
* @param string $name
* The name of the property to set, eg 'timezone'
* @param array|string|integer|float|boolean $value
* The value for the property to set, eg. '+10:00'
* @param string $group
* The group for this property, eg. 'region'
*/
public function set($name, $value, $group = null)
{
if ($this->_forceLowerCase) {
$name = strtolower($name);
$group = strtolower($group);
}
if ($group) {
$this->_properties[$group][$name] = $value;
} else {
$this->_properties[$name] = $value;
}
}
/**
* A quick way to set a large number of properties. Given an associative
* array or a nested associative array (where the key will be the group),
* this function will merge the `$array` with the existing configuration.
* By default the given `$array` will overwrite any existing keys unless
* the `$overwrite` parameter is passed as false.
*
* @since Symphony 2.3.2 The `$overwrite` parameter is available
* @param array $array
* An associative array of properties, 'property' => 'value' or
* 'group' => array('property' => 'value')
* @param boolean $overwrite
* An optional boolean parameter to indicate if it is safe to use array_merge
* or if the provided array should be integrated using the 'set()' method
* to avoid possible change collision. Defaults to false.
*/
public function setArray(array $array, $overwrite = false)
{
if ($overwrite) {
$this->_properties = array_merge($this->_properties, $array);
} else {
foreach ($array as $set => $values) {
foreach ($values as $key => $val) {
self::set($key, $val, $set);
}
}
}
}
/**
* Accessor function for the `$this->_properties`.
*
* @param string $name
* The name of the property to retrieve
* @param string $group
* The group that this property will be in
* @return array|string|integer|float|boolean
* If `$name` or `$group` are not
* provided this function will return the full `$this->_properties`
* array.
*/
public function get($name = null, $group = null)
{
// Return the whole array if no name or index is requested
if (!$name && !$group) {
return $this->_properties;
}
if ($this->_forceLowerCase) {
$name = strtolower($name);
$group = strtolower($group);
}
if ($group) {
return (isset($this->_properties[$group][$name]) ? $this->_properties[$group][$name] : null);
}
return (isset($this->_properties[$name]) ? $this->_properties[$name] : null);
}
/**
* The remove function will unset a property by `$name`.
* It is possible to remove an entire 'group' by passing the group
* name as the `$name`
*
* @param string $name
* The name of the property to unset. This can also be the group name
* @param string $group
* The group of the property to unset
*/
public function remove($name, $group = null)
{
if ($this->_forceLowerCase) {
$name = strtolower($name);
$group = strtolower($group);
}
if ($group && isset($this->_properties[$group][$name])) {
unset($this->_properties[$group][$name]);
} elseif ($this->_properties[$name]) {
unset($this->_properties[$name]);
}
}
/**
* Empties all the Configuration values by setting `$this->_properties`
* to an empty array
*/
public function flush()
{
$this->_properties = array();
}
/**
* This magic `__toString` function converts the internal `$this->_properties`
* array into a string representation. Symphony generates the `MANIFEST/config.php`
* file in this manner.
* @see ArraySerializer::asPHPFile()
* @return string
* A string that contains a array representation of `$this->_properties`.
* This is used by Symphony to write the `config.php` file.
*/
public function __toString()
{
return (new ArraySerializer($this->_properties))->asPHPFile();
}
/**
* Function will write the current Configuration object to
* a specified `$file` with the given `$permissions`.
*
* @param string $file
* the path of the file to write.
* @param integer|null $permissions (optional)
* the permissions as an octal number to set set on the resulting file.
* If this is not provided it will use the permissions defined in [`write_mode`][`file`]
* @return boolean
*/
public function write($file = null, $permissions = null)
{
if (is_null($permissions) && isset($this->_properties['file']['write_mode'])) {
$permissions = $this->_properties['file']['write_mode'];
}
if (is_null($file)) {
$file = CONFIG;
}
$string = (string)$this;
if (function_exists('opcache_invalidate')) {
opcache_invalidate($file, true);
}
return General::writeFile($file, $string, $permissions);
}
}