Documentation

OptionsResolver
in package

Application

implements Options

Validates options and merges them with default values.

Interfaces

Options: Contains resolved option values.

Constants

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 : array<string|int, mixed>: A list of accepted types for each option.
$allowedValues : array<string|int, mixed>: A list of accepted values for each option.
$calling : array<string|int, mixed>: A list of lazy options whose closure is currently being called.
$defaults : array<string|int, mixed>: The default option values.
$defined : array<string|int, mixed>: The names of all defined options.
$deprecated : array<string|int, mixed>: A list of deprecated options.
$given : array<string|int, mixed>: The list of options provided by the user.
$ignoreUndefined : bool: Whether to ignore undefined options.
$info : array<string|int, mixed>: A list of info messages for each option.
$lazy : array<string|int, mixed>: A list of closures for evaluating lazy options.
$locked : bool: 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 : array<string|int, mixed>
$prototype : bool|null: Whether the whole options definition is marked as array prototype.
$prototypeIndex : int|string|null: The prototype array's index that is being read.
$required : array<string|int, mixed>: The names of required options.
$resolved : array<string|int, mixed>: The resolved option values.

Methods

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() : void: Not supported.
offsetUnset() : void: 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
setDefined() : $this: Defines a valid option name.
setDeprecated() : $this: Deprecates an option, allowed types or values.
setIgnoreUndefined() : $this: Sets whether ignore undefined options.
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

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

$allowedTypes

A list of accepted types for each option.


    private
        array<string|int, mixed>
    $allowedTypes
     = []

$allowedValues

A list of accepted values for each option.


    private
        array<string|int, mixed>
    $allowedValues
     = []

$calling

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


    private
        array<string|int, mixed>
    $calling
     = []

This list helps detecting circular dependencies between lazy options.

$defaults

The default option values.


    private
        array<string|int, mixed>
    $defaults
     = []

$defined

The names of all defined options.


    private
        array<string|int, mixed>
    $defined
     = []

$deprecated

A list of deprecated options.


    private
        array<string|int, mixed>
    $deprecated
     = []

$given

The list of options provided by the user.


    private
        array<string|int, mixed>
    $given
     = []

$ignoreUndefined

Whether to ignore undefined options.


    private
        bool
    $ignoreUndefined
     = false

$info

A list of info messages for each option.


    private
        array<string|int, mixed>
    $info
     = []

$lazy

A list of closures for evaluating lazy options.


    private
        array<string|int, mixed>
    $lazy
     = []

$locked

Whether the instance is locked for reading.


    private
        bool
    $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
     = []

$parentsOptions


    private
        array<string|int, mixed>
    $parentsOptions
     = []

$prototype

Whether the whole options definition is marked as array prototype.


    private
        bool|null
    $prototype
     = null

$prototypeIndex

The prototype array's index that is being read.


    private
        int|string|null
    $prototypeIndex
     = null

$required

The names of required options.


    private
        array<string|int, mixed>
    $required
     = []

$resolved

The resolved option values.


    private
        array<string|int, mixed>
    $resolved
     = []

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
$allowedTypes : string|array<string|int, string>: One or more accepted types

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
$allowedValues : mixed: One or more acceptable values/closures

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
$normalizer : Closure
$forcePrepend : bool = false

Return values

$this

clear()

Removes all options.


    public
                    clear() : $this

Return values

$this

count()

Returns the number of set options.


    public
                    count() : int

This may be only a subset of the defined options.

Return values

int

define()

Defines an option configurator with the given name.


    public
                    define(string $option) : OptionConfigurator

Parameters

$option : string

Return values

OptionConfigurator

getDefinedOptions()

Returns the names of all defined options.


    public
                    getDefinedOptions() : array<string|int, string>

Return values

array<string|int, string>

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>

Return values

array<string|int, string>

getRequiredOptions()

Returns the names of all required options.


    public
                    getRequiredOptions() : array<string|int, string>

Return values

array<string|int, string>

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

Return values

bool

isDefined()

Returns whether an option is defined.


    public
                    isDefined(string $option) : bool

Returns true for any option passed to , or .

Parameters

$option : string

Return values

bool

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

Return values

bool

isNested()


    public
                    isNested(string $option) : bool

Parameters

$option : string

Return values

bool

isPrototype()


    public
                    isPrototype() : bool

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

Return values

bool

offsetExists()

Returns whether a resolved option with the given name exists.


    public
                    offsetExists(mixed $option) : bool

Parameters

$option : mixed

Return values

bool

offsetGet()

Returns the resolved value of an option.


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

Parameters

$option : mixed
$triggerDeprecation : bool = true: Whether to trigger the deprecation or not (true by default)

offsetSet()

Not supported.


    public
                    offsetSet(mixed $option, mixed $value) : void

Parameters

$option : mixed
$value : mixed

offsetUnset()

Not supported.


    public
                    offsetUnset(mixed $option) : void

Parameters

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

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> = []

Return values

array<string|int, mixed>

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
$allowedTypes : string|array<string|int, string>: One or more accepted types

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
$allowedValues : mixed: One or more acceptable values/closures

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
$value : mixed

Return values

$this

setDefaults()


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

Parameters

$defaults : array<string|int, mixed>

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

Return values

$this

setDeprecated()

Deprecates an option, allowed types or values.


    public
                    setDeprecated(string $option, string $package, string $version[, string|Closure $message = 'The option "%name%" is deprecated.' ]) : $this

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
$package : string: The name of the composer package that is triggering the deprecation
$version : string: The version of the package that introduced the deprecation
$message : string|Closure = 'The option "%name%" is deprecated.': The deprecation message to use

Return values

$this

setIgnoreUndefined()

Sets whether ignore undefined options.


    public
                    setIgnoreUndefined([bool $ignore = true ]) : $this

Parameters

$ignore : bool = true

Return values

$this

setInfo()

Sets an info message for an option.


    public
                    setInfo(string $option, string $info) : $this

Parameters

$option : string
$info : string

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
$normalizer : Closure

Return values

$this

setPrototype()

Marks the whole options definition as array prototype.


    public
                    setPrototype(bool $prototype) : $this

Parameters

$prototype : bool

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

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

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>

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 = 0 ]) : bool

Parameters

$type : string
$value : mixed
$invalidTypes : array<string|int, mixed>
$level : int = 0

Return values

bool

OptionsResolver in package Application implements Options

Tags

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

VALIDATION_FUNCTIONS

Properties

$allowedTypes

$allowedValues

$calling

$defaults

$defined

$deprecated

$given

$ignoreUndefined

$info

$lazy

$locked

$nested

$normalizers

$parentsOptions

$prototype

$prototypeIndex

$required

$resolved

Methods

addAllowedTypes()

Parameters

Tags

Return values

addAllowedValues()

Parameters

Tags

Return values

addNormalizer()

Parameters

Tags

Return values

clear()

Tags

Return values

count()

Tags

Return values

define()

Parameters

Return values

getDefinedOptions()

Tags

Return values

getInfo()

Parameters

Return values

getMissingOptions()

Return values

getRequiredOptions()

Tags

Return values

hasDefault()

Parameters

Return values

isDefined()

Parameters

Return values

isDeprecated()

Parameters

Return values

isMissing()

Parameters

Return values

isNested()

Parameters

Return values

isPrototype()

Return values

isRequired()

Parameters

OptionsResolver
in package

Application

implements Options