OptionsResolver

$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

$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

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

$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

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

string[] getRequiredOptions()

Returns the names of all required options.

Return Value

string[]

The names of the required options

See also

isRequired()

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

string[] getMissingOptions()

Returns the names of all options missing a default value.

Return Value

string[]

The names of the missing options

See also

isMissing()

$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

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

string[] getDefinedOptions()

Returns the names of all defined options.

Return Value

string[]

The names of the defined options

See also

isDefined()

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

Sets the normalizer for an option.

The normalizer should be a closure with the following signature:

php 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

$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()

$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

$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

$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

$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

$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

$this clear()

Removes all options.

Return Value

$this

Exceptions

AccessException

If called from a lazy option or normalizer

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

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

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()

offsetSet($option, $value)

Not supported.

Parameters

	$option
	$value

Exceptions

AccessException

offsetUnset($option)

Not supported.

Parameters

$option

Exceptions

AccessException

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()

set($option, $value) ^deprecated

^deprecated

since version 2.6, to be removed in 3.0.

Alias of {@link setDefault()}.

Parameters

	$option
	$value

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

overload($option, $value) ^deprecated

^deprecated

since version 2.6, to be removed in 3.0.

Alias of {@link setDefault()}.

Parameters

	$option
	$value

get($option) ^deprecated

^deprecated

since version 2.6, to be removed in 3.0.

Alias of {@link offsetGet()}.

Parameters

$option

has($option) ^deprecated

^deprecated

since version 2.6, to be removed in 3.0.

Alias of {@link offsetExists()}.

Parameters

$option

$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

$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

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