Validates options and merges them with default values.
VALIDATION_FUNCTIONS = ['bool' => 'is_bool', 'boolean' => 'is_bool', 'int' => 'is_int', 'integer' => 'is_int', 'long' => 'is_int', 'float' => 'is_float', 'double' => 'is_float', 'real' => 'is_float', 'numeric' => 'is_numeric', 'string' => 'is_string', 'scalar' => 'is_scalar', 'array' => 'is_array', 'iterable' => 'is_iterable', 'countable' => 'is_countable', 'callable' => 'is_callable', 'object' => 'is_object', 'resource' => 'is_resource']
$nested : \Closure[][]
A list of closure for nested options.
$normalizers : \Closure[][]
A list of normalizer closures.
$locked
Whether the instance is locked for reading.
Once locked, the options cannot be changed anymore. This is necessary in order to avoid inconsistencies during the resolving process. If any option is changed after being read, all evaluated lazy options that depend on this option would become invalid.
setDefault(string $option, mixed $value) : $this
Sets the default value of a given option.
If the default value should be set based on other options, you can pass a closure with the following signature:
function (Options $options) {
// ...
}
The closure will be evaluated when {@link resolve()} is called. The closure has access to the resolved values of other options through the passed {@link Options} instance:
function (Options $options) {
if (isset($options['port'])) {
// ...
}
}
If you want to access the previously set default value, add a second argument to the closure's signature:
$options->setDefault('name', 'Default Name');
$options->setDefault('name', function (Options $options, $previousValue) {
// 'Default Name' === $previousValue
});
This is mostly useful if the configuration of the {@link Options} object is spread across different locations of your code, such as base and sub-classes.
If you want to define nested options, you can pass a closure with the following signature:
$options->setDefault('database', function (OptionsResolver $resolver) {
$resolver->setDefined(['dbname', 'host', 'port', 'user', 'pass']);
}
To get access to the parent options, add a second argument to the closure's signature:
function (OptionsResolver $resolver, Options $parent) {
// 'default' === $parent['connection']
}
| string | $option | The name of the option |
| mixed | $value | The default value of the option |
If called from a lazy option or normalizer
hasDefault(string $option) : bool
Returns whether a default value is set for an option.
Returns true if {@link setDefault()} was called for this option. An option is also considered set if it was set to null.
| string | $option | The option name |
Whether a default value is set
isMissing(string $option) : bool
Returns whether an option is missing a default value.
An option is missing if it was passed to {@link setRequired()}, but not to {@link setDefault()}. This option must be passed explicitly to {@link resolve()}, otherwise an exception will be thrown.
| string | $option | The name of the option |
Whether the option is missing
setDefined(string|string[] $optionNames) : $this
Defines a valid option name.
Defines an option name without setting a default value. The option will be accepted when passed to {@link resolve()}. When not passed, the option will not be included in the resolved options.
| string|string[] | $optionNames | One or more option names |
If called from a lazy option or normalizer
setDeprecated(string $option) : self
Deprecates an option, allowed types or values.
Instead of passing the message, you may also pass a closure with the following signature:
function (Options $options, $value): string {
// ...
}
The closure receives the value as argument and should return a string. Return an empty string to ignore the option deprecation.
The closure is invoked when {@link resolve()} is called. The parameter passed to the closure is the value of the option after validating it and before normalizing it.
| string | $option |
setNormalizer(string $option, \Closure $normalizer) : $this
Sets the normalizer for an option.
The normalizer should be a closure with the following signature:
function (Options $options, $value) {
// ...
}
The closure is invoked when {@link resolve()} is called. The closure has access to the resolved values of other options through the passed {@link Options} instance.
The second parameter passed to the closure is the value of the option.
The resolved option value is set to the return value of the closure.
| string | $option | The option name |
| \Closure | $normalizer | The normalizer |
If the option is undefined
If called from a lazy option or normalizer
addNormalizer(string $option, \Closure $normalizer, bool $forcePrepend = false) : $this
Adds a normalizer for an option.
The normalizer should be a closure with the following signature:
function (Options $options, $value): mixed {
// ...
}
The closure is invoked when {@link resolve()} is called. The closure has access to the resolved values of other options through the passed {@link Options} instance.
The second parameter passed to the closure is the value of the option.
The resolved option value is set to the return value of the closure.
| string | $option | The option name |
| \Closure | $normalizer | The normalizer |
| bool | $forcePrepend | If set to true, prepend instead of appending |
If the option is undefined
If called from a lazy option or normalizer
setAllowedValues(string $option, mixed $allowedValues) : $this
Sets allowed values for an option.
Instead of passing values, you may also pass a closures with the following signature:
function ($value) {
// return true or false
}
The closure receives the value as argument and should return true to accept the value and false to reject the value.
| string | $option | The option name |
| mixed | $allowedValues | One or more acceptable values/closures |
If the option is undefined
If called from a lazy option or normalizer
addAllowedValues(string $option, mixed $allowedValues) : $this
Adds allowed values for an option.
The values are merged with the allowed values defined previously.
Instead of passing values, you may also pass a closures with the following signature:
function ($value) {
// return true or false
}
The closure receives the value as argument and should return true to accept the value and false to reject the value.
| string | $option | The option name |
| mixed | $allowedValues | One or more acceptable values/closures |
If the option is undefined
If called from a lazy option or normalizer
setAllowedTypes(string $option, string|string[] $allowedTypes) : $this
Sets allowed types for an option.
Any type for which a corresponding is_
| string | $option | The option name |
| string|string[] | $allowedTypes | One or more accepted types |
If the option is undefined
If called from a lazy option or normalizer
addAllowedTypes(string $option, string|string[] $allowedTypes) : $this
Adds allowed types for an option.
The types are merged with the allowed types defined previously.
Any type for which a corresponding is_
| string | $option | The option name |
| string|string[] | $allowedTypes | One or more accepted types |
If the option is undefined
If called from a lazy option or normalizer
setInfo(string $option, string $info) : $this
Sets an info message for an option.
| string | $option | |
| string | $info |
If the option is undefined
If called from a lazy option or normalizer
remove(string|string[] $optionNames) : $this
Removes the option with the given name.
Undefined options are ignored.
| string|string[] | $optionNames | One or more option names |
If called from a lazy option or normalizer
resolve(array $options = []) : array
Merges options with the default values stored in the container and validates them.
Exceptions are thrown if:
| array | $options | A map of option names to values |
If an option name is undefined
If an option doesn't fulfill the specified validation rules
If a required option is missing
If there is a cyclic dependency between lazy options and/or normalizers
If a lazy option reads an unavailable option
If called from a lazy option or normalizer
The merged and validated options
offsetGet(string $option, bool $triggerDeprecation = true) : mixed
Returns the resolved value of an option.
| string | $option | The option name |
| bool | $triggerDeprecation | Whether to trigger the deprecation or not (true by default) |
If accessing this method outside of {@link resolve()}
If the option is not set
If the option doesn't fulfill the specified validation rules
If there is a cyclic dependency between lazy options and/or normalizers
The option value
offsetExists(string $option) : bool
Returns whether a resolved option with the given name exists.
| string | $option | The option name |
If accessing this method outside of {@link resolve()}
Whether the option is set
formatValue(mixed $value) : string
Returns a string representation of the value.
This method returns the equivalent PHP tokens for most scalar types (i.e. "false" for false, "1" for 1 etc.). Strings are always wrapped in double quotes (").
| mixed | $value | The value to format as string |