Documentation

OptionsResolver
in package
implements Options

Validates options and merges them with default values.

Tags
author

Bernhard Schussek bschussek@gmail.com

author

Tobias Schultze http://tobion.de

Interfaces, Classes and Traits

Options
Contains resolved option values.

Table of Contents

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']
$allowedTypes  : mixed
A list of accepted types for each option.
$allowedValues  : mixed
A list of accepted values for each option.
$calling  : mixed
A list of lazy options whose closure is currently being called.
$defaults  : mixed
The default option values.
$defined  : mixed
The names of all defined options.
$deprecated  : mixed
A list of deprecated options.
$given  : mixed
The list of options provided by the user.
$info  : mixed
A list of info messages for each option.
$lazy  : mixed
A list of closures for evaluating lazy options.
$locked  : mixed
Whether the instance is locked for reading.
$nested  : array<string|int, array<string|int, Closure>>
A list of closure for nested options.
$normalizers  : array<string|int, array<string|int, Closure>>
A list of normalizer closures.
$parentsOptions  : mixed
$prototype  : mixed
Whether the whole options definition is marked as array prototype.
$prototypeIndex  : mixed
The prototype array's index that is being read.
$required  : mixed
The names of required options.
$resolved  : mixed
The resolved option values.
addAllowedTypes()  : $this
Adds allowed types for an option.
addAllowedValues()  : $this
Adds allowed values for an option.
addNormalizer()  : $this
Adds a normalizer for an option.
clear()  : $this
Removes all options.
count()  : int
Returns the number of set options.
define()  : OptionConfigurator
Defines an option configurator with the given name.
getDefinedOptions()  : array<string|int, string>
Returns the names of all defined options.
getInfo()  : string|null
Gets the info message for an option.
getMissingOptions()  : array<string|int, string>
Returns the names of all options missing a default value.
getRequiredOptions()  : array<string|int, string>
Returns the names of all required options.
hasDefault()  : bool
Returns whether a default value is set for an option.
isDefined()  : bool
Returns whether an option is defined.
isDeprecated()  : bool
isMissing()  : bool
Returns whether an option is missing a default value.
isNested()  : bool
isPrototype()  : bool
isRequired()  : bool
Returns whether an option is required.
offsetExists()  : bool
Returns whether a resolved option with the given name exists.
offsetGet()  : mixed
Returns the resolved value of an option.
offsetSet()  : mixed
Not supported.
offsetUnset()  : mixed
Not supported.
remove()  : $this
Removes the option with the given name.
resolve()  : array<string|int, mixed>
Merges options with the default values stored in the container and validates them.
setAllowedTypes()  : $this
Sets allowed types for an option.
setAllowedValues()  : $this
Sets allowed values for an option.
setDefault()  : $this
Sets the default value of a given option.
setDefaults()  : $this
Sets a list of default values.
setDefined()  : $this
Defines a valid option name.
setDeprecated()  : self
Deprecates an option, allowed types or values.
setInfo()  : $this
Sets an info message for an option.
setNormalizer()  : $this
Sets the normalizer for an option.
setPrototype()  : $this
Marks the whole options definition as array prototype.
setRequired()  : $this
Marks one or more options as required.
formatOptions()  : string
formatValue()  : string
Returns a string representation of the value.
formatValues()  : string
Returns a string representation of a list of values.
getParameterClassName()  : string|null
verifyTypes()  : bool

Constants

VALIDATION_FUNCTIONS

private mixed 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']

Properties

$allowedTypes

A list of accepted types for each option.

private mixed $allowedTypes = []

$allowedValues

A list of accepted values for each option.

private mixed $allowedValues = []

$calling

A list of lazy options whose closure is currently being called.

private mixed $calling = []

This list helps detecting circular dependencies between lazy options.

$defined

The names of all defined options.

private mixed $defined = []

$deprecated

A list of deprecated options.

private mixed $deprecated = []

$given

The list of options provided by the user.

private mixed $given = []

$info

A list of info messages for each option.

private mixed $info = []

$lazy

A list of closures for evaluating lazy options.

private mixed $lazy = []

$locked

Whether the instance is locked for reading.

private mixed $locked = false

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.

$nested

A list of closure for nested options.

private array<string|int, array<string|int, Closure>> $nested = []

$normalizers

A list of normalizer closures.

private array<string|int, array<string|int, Closure>> $normalizers = []

$prototype

Whether the whole options definition is marked as array prototype.

private mixed $prototype

$prototypeIndex

The prototype array's index that is being read.

private mixed $prototypeIndex

$required

The names of required options.

private mixed $required = []

Methods

addAllowedTypes()

Adds allowed types for an option.

public addAllowedTypes(string $option, string|array<string|int, string> $allowedTypes) : $this

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
$option : string

The option name

$allowedTypes : string|array<string|int, string>

One or more accepted types

Tags
throws
UndefinedOptionsException

If the option is undefined

throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

addAllowedValues()

Adds allowed values for an option.

public addAllowedValues(string $option, mixed $allowedValues) : $this

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
$option : string

The option name

$allowedValues : mixed

One or more acceptable values/closures

Tags
throws
UndefinedOptionsException

If the option is undefined

throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

addNormalizer()

Adds a normalizer for an option.

public addNormalizer(string $option, Closure $normalizer[, bool $forcePrepend = false ]) : $this

The normalizer should be a closure with the following signature:

function (Options $options, $value): mixed {
    // ...
}

The closure is invoked when is called. The closure has access to the resolved values of other options through the passed 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
$option : string

The option name

$normalizer : Closure

The normalizer

$forcePrepend : bool = false

If set to true, prepend instead of appending

Tags
throws
UndefinedOptionsException

If the option is undefined

throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

clear()

Removes all options.

public clear() : $this
Tags
throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

count()

Returns the number of set options.

public count() : int

This may be only a subset of the defined options.

Tags
throws
AccessException

If accessing this method outside of

see
Countable::count()
Return values
int —

Number of options

getDefinedOptions()

Returns the names of all defined options.

public getDefinedOptions() : array<string|int, string>
Tags
see
isDefined()
Return values
array<string|int, string> —

The names of the defined options

getInfo()

Gets the info message for an option.

public getInfo(string $option) : string|null
Parameters
$option : string
Return values
string|null —

getMissingOptions()

Returns the names of all options missing a default value.

public getMissingOptions() : array<string|int, string>
Tags
see
isMissing()
Return values
array<string|int, string> —

The names of the missing options

getRequiredOptions()

Returns the names of all required options.

public getRequiredOptions() : array<string|int, string>
Tags
see
isRequired()
Return values
array<string|int, string> —

The names of the required options

hasDefault()

Returns whether a default value is set for an option.

public hasDefault(string $option) : bool

Returns true if was called for this option. An option is also considered set if it was set to null.

Parameters
$option : string

The option name

Return values
bool —

Whether a default value is set

isDefined()

Returns whether an option is defined.

public isDefined(string $option) : bool

Returns true for any option passed to , or .

Parameters
$option : string

The option name

Return values
bool —

Whether the option is defined

isDeprecated()

public isDeprecated(string $option) : bool
Parameters
$option : string
Return values
bool —

isMissing()

Returns whether an option is missing a default value.

public isMissing(string $option) : bool

An option is missing if it was passed to , but not to . This option must be passed explicitly to , otherwise an exception will be thrown.

Parameters
$option : string

The name of the option

Return values
bool —

Whether the option is missing

isNested()

public isNested(string $option) : bool
Parameters
$option : string
Return values
bool —

isRequired()

Returns whether an option is required.

public isRequired(string $option) : bool

An option is required if it was passed to .

Parameters
$option : string

The name of the option

Return values
bool —

Whether the option is required

offsetExists()

Returns whether a resolved option with the given name exists.

public offsetExists(string $option) : bool
Parameters
$option : string

The option name

Tags
throws
AccessException

If accessing this method outside of

see
ArrayAccess::offsetExists()
Return values
bool —

Whether the option is set

offsetGet()

Returns the resolved value of an option.

public offsetGet(string $option[, bool $triggerDeprecation = true ]) : mixed
Parameters
$option : string

The option name

$triggerDeprecation : bool = true

Whether to trigger the deprecation or not (true by default)

Tags
throws
AccessException

If accessing this method outside of

throws
NoSuchOptionException

If the option is not set

throws
InvalidOptionsException

If the option doesn't fulfill the specified validation rules

throws
OptionDefinitionException

If there is a cyclic dependency between lazy options and/or normalizers

Return values
mixed —

The option value

offsetSet()

Not supported.

public offsetSet(mixed $option, mixed $value) : mixed
Parameters
$option : mixed
$value : mixed
Tags
throws
AccessException
Return values
mixed —

offsetUnset()

Not supported.

public offsetUnset(mixed $option) : mixed
Parameters
$option : mixed
Tags
throws
AccessException
Return values
mixed —

remove()

Removes the option with the given name.

public remove(string|array<string|int, string> $optionNames) : $this

Undefined options are ignored.

Parameters
$optionNames : string|array<string|int, string>

One or more option names

Tags
throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

resolve()

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

public resolve([array<string|int, mixed> $options = [] ]) : array<string|int, mixed>

Exceptions are thrown if:

  • Undefined options are passed;
  • Required options are missing;
  • Options have invalid types;
  • Options have invalid values.
Parameters
$options : array<string|int, mixed> = []

A map of option names to values

Tags
throws
UndefinedOptionsException

If an option name is undefined

throws
InvalidOptionsException

If an option doesn't fulfill the specified validation rules

throws
MissingOptionsException

If a required option is missing

throws
OptionDefinitionException

If there is a cyclic dependency between lazy options and/or normalizers

throws
NoSuchOptionException

If a lazy option reads an unavailable option

throws
AccessException

If called from a lazy option or normalizer

Return values
array<string|int, mixed> —

The merged and validated options

setAllowedTypes()

Sets allowed types for an option.

public setAllowedTypes(string $option, string|array<string|int, string> $allowedTypes) : $this

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

Parameters
$option : string

The option name

$allowedTypes : string|array<string|int, string>

One or more accepted types

Tags
throws
UndefinedOptionsException

If the option is undefined

throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

setAllowedValues()

Sets allowed values for an option.

public setAllowedValues(string $option, mixed $allowedValues) : $this

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
$option : string

The option name

$allowedValues : mixed

One or more acceptable values/closures

Tags
throws
UndefinedOptionsException

If the option is undefined

throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

setDefault()

Sets the default value of a given option.

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

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 is called. The closure has access to the resolved values of other options through the passed 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 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']
}
Parameters
$option : string

The name of the option

$value : mixed

The default value of the option

Tags
throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

setDefaults()

Sets a list of default values.

public setDefaults(array<string|int, mixed> $defaults) : $this
Parameters
$defaults : array<string|int, mixed>

The default values to set

Tags
throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

setDefined()

Defines a valid option name.

public setDefined(string|array<string|int, string> $optionNames) : $this

Defines an option name without setting a default value. The option will be accepted when passed to . When not passed, the option will not be included in the resolved options.

Parameters
$optionNames : string|array<string|int, string>

One or more option names

Tags
throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

setDeprecated()

Deprecates an option, allowed types or values.

public setDeprecated(string $option) : self

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 is called. The parameter passed to the closure is the value of the option after validating it and before normalizing it.

Parameters
$option : string
Return values
self —

setInfo()

Sets an info message for an option.

public setInfo(string $option, string $info) : $this
Parameters
$option : string
$info : string
Tags
throws
UndefinedOptionsException

If the option is undefined

throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

setNormalizer()

Sets the normalizer for an option.

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

The normalizer should be a closure with the following signature:

function (Options $options, $value) {
    // ...
}

The closure is invoked when is called. The closure has access to the resolved values of other options through the passed 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
$option : string

The option name

$normalizer : Closure

The normalizer

Tags
throws
UndefinedOptionsException

If the option is undefined

throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

setPrototype()

Marks the whole options definition as array prototype.

public setPrototype(bool $prototype) : $this
Parameters
$prototype : bool
Tags
throws
AccessException

If called from a lazy option, a normalizer or a root definition

Return values
$this —

setRequired()

Marks one or more options as required.

public setRequired(string|array<string|int, string> $optionNames) : $this
Parameters
$optionNames : string|array<string|int, string>

One or more option names

Tags
throws
AccessException

If called from a lazy option or normalizer

Return values
$this —

formatOptions()

private formatOptions(array<string|int, mixed> $options) : string
Parameters
$options : array<string|int, mixed>
Return values
string —

formatValue()

Returns a string representation of the value.

private formatValue(mixed $value) : string

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

Parameters
$value : mixed

The value to format as string

Return values
string —

formatValues()

Returns a string representation of a list of values.

private formatValues(array<string|int, mixed> $values) : string

Each of the values is converted to a string using . The values are then concatenated with commas.

Parameters
$values : array<string|int, mixed>
Tags
see
formatValue()
Return values
string —

getParameterClassName()

private getParameterClassName(ReflectionParameter $parameter) : string|null
Parameters
$parameter : ReflectionParameter
Return values
string|null —

verifyTypes()

private verifyTypes(string $type, mixed $value, array<string|int, mixed> &$invalidTypes, int $level) : bool
Parameters
$type : string
$value : mixed
$invalidTypes : array<string|int, mixed>
$level : int
Return values
bool —

Search results