class OptionsResolver implements Options, OptionsResolverInterface

Validates options and merges them with default values.

Constants

OPTIONS_INTERFACE

The fully qualified name of the {@link Options} interface.

Methods

$this
setDefault(string $option, mixed $value)

Sets the default value of a given option.

$this
setDefaults(array $defaults)

Sets a list of default values.

bool
hasDefault(string $option)

Returns whether a default value is set for an option.

$this
setRequired(array $optionNames)

Marks one or more options as required.

bool
isRequired(string $option)

Returns whether an option is required.

string[]
getRequiredOptions()

Returns the names of all required options.

bool
isMissing(string $option)

Returns whether an option is missing a default value.

string[]
getMissingOptions()

Returns the names of all options missing a default value.

$this
setDefined(string|string[] $optionNames)

Defines a valid option name.

bool
isDefined(string $option)

Returns whether an option is defined.

string[]
getDefinedOptions()

Returns the names of all defined options.

$this
setNormalizer(string $option, Closure $normalizer)

Sets the normalizer for an option.

$this
setNormalizers(array $normalizers) deprecated

Sets the normalizers for an array of options.

$this
setAllowedValues(string $option, array $allowedValues = null)

Sets allowed values for an option.

$this
addAllowedValues(string $option, array $allowedValues = null)

Adds allowed values for an option.

$this
setAllowedTypes(string $option, array $allowedTypes = null)

Sets allowed types for an option.

$this
addAllowedTypes(string $option, array $allowedTypes = null)

Adds allowed types for an option.

$this
remove(string|string[] $optionNames)

Removes the option with the given name.

$this
clear()

Removes all options.

array
resolve(array $options = array())

Merges options with the default values stored in the container and validates them.

mixed
offsetGet(string $option)

Returns the resolved value of an option.

bool
offsetExists(string $option)

Returns whether a resolved option with the given name exists.

offsetSet($option, $value)

Not supported.

offsetUnset($option)

Not supported.

int
count()

Returns the number of set options.

set($option, $value) deprecated

Alias of {@link setDefault()}.

replace(array $defaults) deprecated

Shortcut for {@link clear()} and {@link setDefaults()}.

overload($option, $value) deprecated

Alias of {@link setDefault()}.

get($option) deprecated

Alias of {@link offsetGet()}.

has($option) deprecated

Alias of {@link offsetExists()}.

$this
replaceDefaults(array $defaultValues) deprecated

Shortcut for {@link clear()} and {@link setDefaults()}.

$this
setOptional(array $optionNames) deprecated

Alias of {@link setDefined()}.

bool
isKnown(string $option) deprecated

Alias of {@link isDefined()}.

Details

at line line 141
$this setDefault(string $option, mixed $value)

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.

Parameters

string $option The name of the option
mixed $value The default value of the option

Return Value

$this

Exceptions

AccessException If called from a lazy option or normalizer

at line line 204
$this setDefaults(array $defaults)

Sets a list of default values.

Parameters

array $defaults The default values to set

Return Value

$this

Exceptions

AccessException If called from a lazy option or normalizer

at line line 223
bool hasDefault(string $option)

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.

Parameters

string $option The option name

Return Value

bool Whether a default value is set

at line line 237
$this setRequired(array $optionNames)

Marks one or more options as required.

Parameters

array $optionNames A list of option names

Return Value

$this

Exceptions

AccessException If called from a lazy option or normalizer

at line line 260
bool isRequired(string $option)

Returns whether an option is required.

An option is required if it was passed to {@link setRequired()}.

Parameters

string $option The name of the option

Return Value

bool Whether the option is required

at line line 272
string[] getRequiredOptions()

Returns the names of all required options.

Return Value

string[] The names of the required options

See also

isRequired()

at line line 288
bool isMissing(string $option)

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.

Parameters

string $option The name of the option

Return Value

bool Whether the option is missing

at line line 300
string[] getMissingOptions()

Returns the names of all options missing a default value.

Return Value

string[] The names of the missing options

See also

isMissing()

at line line 318
$this setDefined(string|string[] $optionNames)

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.

Parameters

string|string[] $optionNames One or more option names

Return Value

$this

Exceptions

AccessException If called from a lazy option or normalizer

at line line 341
bool isDefined(string $option)

Returns whether an option is defined.

Returns true for any option passed to {@link setDefault()}, {@link setRequired()} or {@link setDefined()}.

Parameters

string $option The option name

Return Value

bool Whether the option is defined

at line line 353
string[] getDefinedOptions()

Returns the names of all defined options.

Return Value

string[] The names of the defined options

See also

isDefined()

at line line 384
$this setNormalizer(string $option, Closure $normalizer)

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.

Parameters

string $option The option name
Closure $normalizer The normalizer

Return Value

$this

Exceptions

UndefinedOptionsException If the option is undefined
AccessException If called from a lazy option or normalizer

at line line 415
$this setNormalizers(array $normalizers) deprecated

deprecated since version 2.6, to be removed in 3.0.

Sets the normalizers for an array of options.

Parameters

array $normalizers An array of closures

Return Value

$this

Exceptions

UndefinedOptionsException If the option is undefined
AccessException If called from a lazy option or normalizer

See also

setNormalizer()

at line line 447
$this setAllowedValues(string $option, array $allowedValues = null)

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.

Parameters

string $option The option name
array $allowedValues A list of option names as keys and arrays with values acceptable for that option as values

Return Value

$this

Exceptions

UndefinedOptionsException If the option is undefined
AccessException If called from a lazy option or normalizer

at line line 499
$this addAllowedValues(string $option, array $allowedValues = null)

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.

Parameters

string $option The option name
array $allowedValues A list of option names as keys and arrays with values acceptable for that option as values

Return Value

$this

Exceptions

UndefinedOptionsException If the option is undefined
AccessException If called from a lazy option or normalizer

at line line 551
$this setAllowedTypes(string $option, array $allowedTypes = null)

Sets allowed types for an option.

Any type for which a corresponding is_() function exists is acceptable. Additionally, fully-qualified class or interface names may be passed.

Parameters

string $option The option name
array $allowedTypes A list of option names as keys and type names passed as string or array as values

Return Value

$this

Exceptions

UndefinedOptionsException If the option is undefined
AccessException If called from a lazy option or normalizer

at line line 597
$this addAllowedTypes(string $option, array $allowedTypes = null)

Adds allowed types for an option.

The types are merged with the allowed types defined previously.

Any type for which a corresponding is_() function exists is acceptable. Additionally, fully-qualified class or interface names may be passed.

Parameters

string $option The option name
array $allowedTypes A list of option names as keys and type names passed as string or array as values

Return Value

$this

Exceptions

UndefinedOptionsException If the option is undefined
AccessException If called from a lazy option or normalizer

at line line 641
$this remove(string|string[] $optionNames)

Removes the option with the given name.

Undefined options are ignored.

Parameters

string|string[] $optionNames One or more option names

Return Value

$this

Exceptions

AccessException If called from a lazy option or normalizer

at line line 662
$this clear()

Removes all options.

Return Value

$this

Exceptions

AccessException If called from a lazy option or normalizer

at line line 704
array resolve(array $options = array())

Merges options with the default values stored in the container and validates them.

Exceptions are thrown if:

  • Undefined options are passed;
  • Required options are missing;
  • Options have invalid types;
  • Options have invalid values.

Parameters

array $options The custom option values

Return Value

array A list of options and their values

Exceptions

UndefinedOptionsException If an option name is undefined
InvalidOptionsException If an option doesn't fulfill the specified validation rules
MissingOptionsException If a required option is missing
OptionDefinitionException If there is a cyclic dependency between lazy options and/or normalizers
NoSuchOptionException If a lazy option reads an unavailable option
AccessException If called from a lazy option or normalizer

at line line 765
mixed offsetGet(string $option)

Returns the resolved value of an option.

Parameters

string $option The option name

Return Value

mixed The option value

Exceptions

AccessException If accessing this method outside of {@link resolve()}
NoSuchOptionException If the option is not set
InvalidOptionsException If the option doesn't fulfill the specified validation rules
OptionDefinitionException If there is a cyclic dependency between lazy options and/or normalizers

at line line 927
bool offsetExists(string $option)

Returns whether a resolved option with the given name exists.

Parameters

string $option The option name

Return Value

bool Whether the option is set

Exceptions

AccessException If accessing this method outside of {@link resolve()}

See also

\ArrayAccess::offsetExists()

at line line 941
offsetSet($option, $value)

Not supported.

Parameters

$option
$value

Exceptions

AccessException

at line line 951
offsetUnset($option)

Not supported.

Parameters

$option

Exceptions

AccessException

at line line 967
int count()

Returns the number of set options.

This may be only a subset of the defined options.

Return Value

int Number of options

Exceptions

AccessException If accessing this method outside of {@link resolve()}

See also

\Countable::count()

at line line 981
set($option, $value) deprecated

deprecated since version 2.6, to be removed in 3.0.

Alias of {@link setDefault()}.

Parameters

$option
$value

at line line 993
replace(array $defaults) deprecated

deprecated since version 2.6, to be removed in 3.0.

Shortcut for {@link clear()} and {@link setDefaults()}.

Parameters

array $defaults

at line line 1007
overload($option, $value) deprecated

deprecated since version 2.6, to be removed in 3.0.

Alias of {@link setDefault()}.

Parameters

$option
$value

at line line 1019
get($option) deprecated

deprecated since version 2.6, to be removed in 3.0.

Alias of {@link offsetGet()}.

Parameters

$option

at line line 1031
has($option) deprecated

deprecated since version 2.6, to be removed in 3.0.

Alias of {@link offsetExists()}.

Parameters

$option

at line line 1043
$this replaceDefaults(array $defaultValues) deprecated

deprecated since version 2.6, to be removed in 3.0.

Shortcut for {@link clear()} and {@link setDefaults()}.

Parameters

array $defaultValues A list of option names as keys and default values or closures as values

Return Value

$this

at line line 1057
$this setOptional(array $optionNames) deprecated

deprecated since version 2.6, to be removed in 3.0.

Alias of {@link setDefined()}.

Parameters

array $optionNames A list of option names

Return Value

$this

at line line 1069
bool isKnown(string $option) deprecated

deprecated since version 2.6, to be removed in 3.0.

Alias of {@link isDefined()}.

Parameters

string $option The name of the option

Return Value

bool Whether the option is known