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

public static 
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

protected static 
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.

protected static 
type_mismatch()

What to do if there's a type mismatch.

public static 
inst()

Get the current active Config instance.

public static 
set_instance(Config $instance)

Set the current active Config instance.

public static 
nest()

Make the newly active Config be a copy of the current active Config instance.

public static 
unnest()

Change the active Config back to the Config instance the current active Config object was copied from.

public
__construct()

Each copy of the Config object need's it's own cache, so changes don't leak through to other instances.

public
__clone()

No description

public
public
pushConfigYamlManifest(SS_ConfigManifest $manifest)

Add another manifest to the list of config manifests to search through.

public
forClass($class)

Get an accessor that returns results by class by default.

public 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

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

public static 
merge_high_into_low($result, $value)

No description

public static 
merge_low_into_high($result, $value, $suppress)

No description

public static 
check_value_contained_in_suppress_array($v, $suppresses)

No description

protected static 
check_key_or_value_contained_in_suppress_array($k, $v, $suppresses)

No description

protected static 
filter_array_by_suppress_array($array, $suppress)

No description

public
extraConfigSourcesChanged($class)

No description

protected
getUncached($class, $name, $sourceOptions, $result, $suppress, $tags)

No description

public
array|scalar
get($class, $name, int $sourceOptions = 0, $result = null, $suppress = null)

Get the config value associated for a given class and property

public
update(string $class, string $name, $val)

Update a configuration value

public
remove(string $class, string $name)

Remove a configuration value

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

Return Value

SS_Object

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.

Parameters

$val

any - The value

Return Value

int
  • One of ISNT_ARRAY or IS_ARRAY

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.

Return Value

Config

static Config set_instance(Config $instance)

Set the current active Config instance.

Config objects should not normally be manually created.

A use case for replacing the active configuration set would be for creating an isolated environment for unit tests.

Parameters

Config $instance

New instance of Config to assign

Return Value

Config

Reference to new active 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.

Return Value

Config

Reference to new active Config instance

static Config unnest()

Change the active Config back to the Config instance the current active Config object was copied from.

Return Value

Config

Reference to new active Config instance

__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

Parameters

SS_ConfigStaticManifest $manifest

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

Parameters

SS_ConfigManifest $manifest

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

Parameters

$class

Return Value

Config_ForClass

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

Parameters

$dest

array - The existing high priority associative array

$src

array - The low priority associative array to merge in

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

Parameters

$dest

array - The existing low priority associative array

$src

array - The high priority array to merge in

static merge_high_into_low($result, $value)

No description

Parameters

$result
$value

static merge_low_into_high($result, $value, $suppress)

No description

Parameters

$result
$value
$suppress

static check_value_contained_in_suppress_array($v, $suppresses)

No description

Parameters

$v
$suppresses

static protected check_key_or_value_contained_in_suppress_array($k, $v, $suppresses)

No description

Parameters

$k
$v
$suppresses

static protected filter_array_by_suppress_array($array, $suppress)

No description

Parameters

$array
$suppress

extraConfigSourcesChanged($class)

No description

Parameters

$class

protected getUncached($class, $name, $sourceOptions, $result, $suppress, $tags)

No description

Parameters

$class
$name
$sourceOptions
$result
$suppress
$tags

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.

Parameters

$class

string - The name of the class to get the value for

$name

string - The property to get the value for

int $sourceOptions

Bitmask which can be set to some combintain of Config::UNINHERITED, Config::FIRST_SET, and Config::EXCLUDE_EXTENSIONS.

Config::UNINHERITED does not include parent classes when merging configuration fragments Config::FIRST_SET stops inheriting once the first class that sets a value (even an empty value) is encoutered Config::EXCLUDE_EXTRA_SOURCES does not include any additional static sources (such as extensions)

Config::INHERITED is a utility constant that can be used to mean "none of the above", equvilient to 0 Setting both Config::UNINHERITED and Config::FIRST_SET behaves the same as just Config::UNINHERITED

should the parent classes value be merged in as the lowest priority source?

$result

array|scalar Reference to a variable to put the result in. Also returned, so this can be left as null safely. If you do pass a value, it will be treated as the highest priority value in the result chain

$suppress

array Internal use when called by child classes. Array of mask pairs to filter value by

Return Value

array|scalar

The value of the config item, or null if no value set. Could be an associative array, sequential array or scalar depending on value (see class docblock)

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.

Parameters

string $class

The class to update a configuration value for

string $name

The configuration property name to update

$val

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.

Parameters

string $class

The class to remove a configuration value from

string $name

The configuration name

Matching is always by "==", not by "==="