Properties

$defined

$defined : 

The names of all defined options.

Type

$defaults

$defaults : 

The default option values.

Type

$required

$required : 

The names of required options.

Type

$resolved

$resolved : 

The resolved option values.

Type

$normalizers

$normalizers : array<mixed,\Closure>

A list of normalizer closures.

Type

array<mixed,\Closure>

$allowedValues

$allowedValues : 

A list of accepted values for each option.

Type

$allowedTypes

$allowedTypes : 

A list of accepted types for each option.

Type

$lazy

$lazy : 

A list of closures for evaluating lazy options.

Type

$calling

$calling : 

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

This list helps detecting circular dependencies between lazy options.

Type

$locked

$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.

Type

$typeAliases

$typeAliases : 

Type

Methods

setDefault()

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 \Symfony\Component\OptionsResolver\resolve() is called. The closure has access to the resolved values of other options through the passed 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 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

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

setDefaults()

setDefaults(array  $defaults) : $this

Sets a list of default values.

Parameters

array $defaults

The default values to set

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

hasDefault()

hasDefault(string  $option) : boolean

Returns whether a default value is set for an option.

Returns true if \Symfony\Component\OptionsResolver\setDefault() was called for this option. An option is also considered set if it was set to null.

Parameters

string $option

The option name

Returns

boolean —

Whether a default value is set

setRequired()

setRequired(string|array<mixed,string>  $optionNames) : $this

Marks one or more options as required.

Parameters

string|array<mixed,string> $optionNames

One or more option names

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

isRequired()

isRequired(string  $option) : boolean

Returns whether an option is required.

An option is required if it was passed to \Symfony\Component\OptionsResolver\setRequired().

Parameters

string $option

The name of the option

Returns

boolean —

Whether the option is required

getRequiredOptions()

getRequiredOptions() : array<mixed,string>

Returns the names of all required options.

Returns

array<mixed,string> —

The names of the required options

isMissing()

isMissing(string  $option) : boolean

Returns whether an option is missing a default value.

An option is missing if it was passed to \Symfony\Component\OptionsResolver\setRequired(), but not to \Symfony\Component\OptionsResolver\setDefault(). This option must be passed explicitly to \Symfony\Component\OptionsResolver\resolve(), otherwise an exception will be thrown.

Parameters

string $option

The name of the option

Returns

boolean —

Whether the option is missing

getMissingOptions()

getMissingOptions() : array<mixed,string>

Returns the names of all options missing a default value.

Returns

array<mixed,string> —

The names of the missing options

setDefined()

setDefined(string|array<mixed,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 \Symfony\Component\OptionsResolver\resolve(). When not passed, the option will not be included in the resolved options.

Parameters

string|array<mixed,string> $optionNames

One or more option names

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

isDefined()

isDefined(string  $option) : boolean

Returns whether an option is defined.

Returns true for any option passed to \Symfony\Component\OptionsResolver\setDefault(), \Symfony\Component\OptionsResolver\setRequired() or \Symfony\Component\OptionsResolver\setDefined().

Parameters

string $option

The option name

Returns

boolean —

Whether the option is defined

getDefinedOptions()

getDefinedOptions() : array<mixed,string>

Returns the names of all defined options.

Returns

array<mixed,string> —

The names of the defined options

setNormalizer()

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 \Symfony\Component\OptionsResolver\resolve() is called. The closure has access to the resolved values of other options through the passed 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

Throws

\Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException

If the option is undefined

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

setAllowedValues()

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.

Parameters

string $option

The option name

mixed $allowedValues

One or more acceptable values/closures

Throws

\Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException

If the option is undefined

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

addAllowedValues()

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.

Parameters

string $option

The option name

mixed $allowedValues

One or more acceptable values/closures

Throws

\Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException

If the option is undefined

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

setAllowedTypes()

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

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

string|array<mixed,string> $allowedTypes

One or more accepted types

Throws

\Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException

If the option is undefined

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

addAllowedTypes()

addAllowedTypes(string  $option, string|array<mixed,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_() function exists is acceptable. Additionally, fully-qualified class or interface names may be passed.

Parameters

string $option

The option name

string|array<mixed,string> $allowedTypes

One or more accepted types

Throws

\Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException

If the option is undefined

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

remove()

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

Removes the option with the given name.

Undefined options are ignored.

Parameters

string|array<mixed,string> $optionNames

One or more option names

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

clear()

clear() : $this

Removes all options.

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

$this

resolve()

resolve(array  $options = array()) : 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

A map of option names to values

Throws

\Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException

If an option name is undefined

\Symfony\Component\OptionsResolver\Exception\InvalidOptionsException

If an option doesn't fulfill the specified validation rules

\Symfony\Component\OptionsResolver\Exception\MissingOptionsException

If a required option is missing

\Symfony\Component\OptionsResolver\Exception\OptionDefinitionException

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

\Symfony\Component\OptionsResolver\Exception\NoSuchOptionException

If a lazy option reads an unavailable option

\Symfony\Component\OptionsResolver\Exception\AccessException

If called from a lazy option or normalizer

Returns

array —

The merged and validated options

offsetGet()

offsetGet(string  $option) : mixed

Returns the resolved value of an option.

Parameters

string $option

The option name

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

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

\Symfony\Component\OptionsResolver\Exception\NoSuchOptionException

If the option is not set

\Symfony\Component\OptionsResolver\Exception\InvalidOptionsException

If the option doesn't fulfill the specified validation rules

\Symfony\Component\OptionsResolver\Exception\OptionDefinitionException

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

Returns

mixed —

The option value

offsetExists()

offsetExists(string  $option) : boolean

Returns whether a resolved option with the given name exists.

Parameters

string $option

The option name

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

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

Returns

boolean —

Whether the option is set

offsetSet()

offsetSet(  $option,   $value) 

Not supported.

Parameters

$option
$value

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

offsetUnset()

offsetUnset(  $option) 

Not supported.

Parameters

$option

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

count()

count() : integer

Returns the number of set options.

This may be only a subset of the defined options.

Throws

\Symfony\Component\OptionsResolver\Exception\AccessException

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

Returns

integer —

Number of options

verifyTypes()

verifyTypes(string  $type, mixed  $value, array  $invalidTypes) : boolean

Parameters

string $type
mixed $value
array $invalidTypes

Returns

boolean

verifyArrayType()

verifyArrayType(  $type, array  $value, array  $invalidTypes,   $level) : boolean

Parameters

$type
array $value
array $invalidTypes
$level

Returns

boolean

formatTypeOf()

formatTypeOf(mixed  $value, string  $type) : string

Returns a string representation of the type of the value.

This method should be used if you pass the type of a value as message parameter to a constraint violation. Note that such parameters should usually not be included in messages aimed at non-technical people.

Parameters

mixed $value

The value to return the type of

string $type

Returns

string —

The type of the value

formatValue()

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

Parameters

mixed $value

The value to format as string

Returns

string —

The string representation of the passed value

formatValues()

formatValues(array  $values) : string

Returns a string representation of a list of values.

Each of the values is converted to a string using \Symfony\Component\OptionsResolver\formatValue(). The values are then concatenated with commas.

Parameters

array $values

A list of values

Returns

string —

The string representation of the value list

isValueValidType()

isValueValidType(  $type,   $value) 

Parameters

$type
$value

getInvalidValues()

getInvalidValues(array  $arrayValues,   $type) : array

Parameters

array $arrayValues
$type

Returns

array