Config
class Config (View source)
The configuration system works like this:
Each class has a set of named properties
Each named property can contain either
- An array
- A non-array value
If the value is an array, each value in the array may also be one of those three types.
A property can have a value specified in multiple locations, each of which have a hard coded or explicit priority. We combine all these values together into a "composite" value using rules that depend on the priority order of the locations to give the final value, using these rules:
-
If the value is an array, each array is added to the beginning of the composite array in ascending priority order. If a higher priority item has a non-integer key which is the same as a lower priority item, the value of those items is merged using these same rules, and the result of the merge is located in the same location the higher priority item would be if there was no key clash. Other than in this key-clash situation, within the particular array, order is preserved.
-
If the value is not an array, the highest priority value is used without any attempt to merge.
It is an error to have mixed types of the same named property in different locations (but an error will not necessarily be raised due to optimizations in the lookup code).
The exception to this is "false-ish" values - empty arrays, empty strings, etc. When merging a non-false-ish value with a false-ish value, the result will be the non-false-ish value regardless of priority. When merging two false-ish values the result will be the higher priority false-ish value.
The locations that configuration values are taken from in highest -> lowest priority order.
-
Any values set via a call to Config#update.
-
The configuration values taken from the YAML files in _config directories (internally sorted in before / after order, where the item that is latest is highest priority).
-
Any static set on an "additional static source" class (such as an extension) named the same as the name of the property.
-
Any static set on the class named the same as the name of the property.
-
The composite configuration value of the parent class of this class.
At some of these levels you can also set masks. These remove values from the composite value at their priority point rather than add. They are much simpler. They consist of a list of key / value pairs. When applied against the current composite value:
-
If the composite value is a sequential array, any member of that array that matches any value in the mask is removed.
-
If the composite value is an associative array, any member of that array that matches both the key and value of any pair in the mask is removed.
-
If the composite value is not an array, if that value matches any value in the mask it is removed.
Constants
| INHERITED |
source options bitmask value - merge all parent configuration in as
lowest priority. |
| UNINHERITED |
source options bitmask value - only get configuration set for this
specific class, not any of it's parents. |
| FIRST_SET |
source options bitmask value - inherit, but stop on the first class
that actually provides a value (event an empty value). |
| EXCLUDE_EXTRA_SOURCES |
|
| ISNT_ARRAY |
Return flag for get_value_type indicating value is a scalar (or really
just not-an-array, at least ATM) |
| IS_ARRAY |
Return flag for get_value_type indicating value is an array. |
Properties
| protected static | $instance | |||
| protected | array | $cache | ||
| protected | Config | $nestedFrom | ||
| protected | array | $overrides | ||
| protected | array | $suppresses | ||
| protected | array | $staticManifests | ||
| protected | $manifests | |||
| protected static | $for_class_instances | |||
| protected | $extraConfigSources |
Methods
Get a marker class instance that is used to do a "remove anything with this key" by adding $key => Config::anything() to the suppress array
Get whether the value is an array or not. Used to be more complicated, but still nice sugar to have an enum to compare and not just a true / false value.
Change the active Config back to the Config instance the current active Config object was copied from.
Each copy of the Config object need's it's own cache, so changes don't leak through to other instances.
Add another manifest to the list of config manifests to search through.
Merge a lower priority associative array into an existing higher priority associative array, as per the class docblock rules
Merge a higher priority assocative array into an existing lower priority associative array, as per the class docblock rules.
Get the config value associated for a given class and property
Details
static SS_Object
anything()
Get a marker class instance that is used to do a "remove anything with this key" by adding $key => Config::anything() to the suppress array
static protected int
get_value_type($val)
Get whether the value is an array or not. Used to be more complicated, but still nice sugar to have an enum to compare and not just a true / false value.
static protected
type_mismatch()
What to do if there's a type mismatch.
static Config
inst()
Get the current active Config instance.
Configs should not normally be manually created.
In general use you will use this method to obtain the current Config instance.
static Config
nest()
Make the newly active Config be a copy of the current active Config instance.
You can then make changes to the configuration by calling update and remove on the new value returned by Config::inst(), and then discard those changes later by calling unnest.
static Config
unnest()
Change the active Config back to the Config instance the current active Config object was copied from.
__construct()
Each copy of the Config object need's it's own cache, so changes don't leak through to other instances.
__clone()
No description
pushConfigStaticManifest(SS_ConfigStaticManifest $manifest)
No description
pushConfigYamlManifest(SS_ConfigManifest $manifest)
Add another manifest to the list of config manifests to search through.
WARNING: Config manifests to not merge entries, and do not solve before/after rules inter-manifest - instead, the last manifest to be added always wins
Config_ForClass
forClass($class)
Get an accessor that returns results by class by default.
Shouldn't be overridden, since there might be many Config_ForClass instances already held in the wild. Each Config_ForClass instance asks the current_instance of Config for the actual result, so override that instead
static
merge_array_low_into_high($dest, $src)
Merge a lower priority associative array into an existing higher priority associative array, as per the class docblock rules
It is assumed you've already checked that you've got two associative arrays, not scalars or sequential arrays
static
merge_array_high_into_low($dest, $src)
Merge a higher priority assocative array into an existing lower priority associative array, as per the class docblock rules.
Much more expensive that the other way around, as there's no way to insert an associative k/v pair into an array at the top of the array
static
merge_high_into_low($result, $value)
No description
static
merge_low_into_high($result, $value, $suppress)
No description
static
check_value_contained_in_suppress_array($v, $suppresses)
No description
static protected
check_key_or_value_contained_in_suppress_array($k, $v, $suppresses)
No description
static protected
filter_array_by_suppress_array($array, $suppress)
No description
extraConfigSourcesChanged($class)
No description
protected
getUncached($class, $name, $sourceOptions, $result, $suppress, $tags)
No description
array|scalar
get($class, $name, int $sourceOptions = 0, $result = null, $suppress = null)
Get the config value associated for a given class and property
This merges all current sources and overrides together to give final value todo: Currently this is done every time. This function is an inner loop function, so we really need to be caching heavily here.
update(string $class, string $name, $val)
Update a configuration value
Configuration is modify only. The value passed is merged into the existing configuration. If you want to replace the current array value, you'll need to call remove first.
remove(string $class, string $name)
Remove a configuration value
You can specify a key, a key and a value, or neither. Either argument can be Config::anything(), which is what is defaulted to if you don't specify something
This removes any current configuration value that matches the key and/or value specified
Works like this:
- Check the current override array, and remove any values that match the arguments provided
- Keeps track of the arguments passed to this method, and in get filters everything except the current override array to exclude any match
This way we can re-set anything removed by a call to this function by calling set. Because the current override array is only filtered immediately on calling this remove method, that value will then be exposed. However, every other source is filtered on request, so no amount of changes to parent's configuration etc can override a remove call.