W3cubDocs

/Symfony 2.7

Symfony\Component\OptionsResolver\OptionsResolver

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

OptionsResolver setDefault(string $option, mixed $value)

Sets the default value of a given option.

OptionsResolver setDefaults(array $defaults)

Sets a list of default values.

bool hasDefault(string $option)

Returns whether a default value is set for an option.

OptionsResolver setRequired(string|string[] $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.

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

OptionsResolver setNormalizer(string $option, Closure $normalizer)

Sets the normalizer for an option.

OptionsResolverInterface setNormalizers(array $normalizers)

Sets normalizers that are applied on resolved options.

OptionsResolver setAllowedValues(string $option, mixed $allowedValues = null)

Sets allowed values for an option.

OptionsResolver addAllowedValues(string $option, mixed $allowedValues = null)

Adds allowed values for an option.

OptionsResolver setAllowedTypes(string $option, string|string[] $allowedTypes = null)

Sets allowed types for an option.

OptionsResolver addAllowedTypes(string $option, string|string[] $allowedTypes = null)

Adds allowed types for an option.

OptionsResolver remove(string|string[] $optionNames)

Removes the option with the given name.

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

Alias of {@link setDefault()}.

replace(array $defaults)

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

overload($option, $value)

Alias of {@link setDefault()}.

get($option)

Alias of {@link offsetGet()}.

has($option)

Alias of {@link offsetExists()}.

OptionsResolverInterface replaceDefaults(array $defaultValues)

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

OptionsResolverInterface setOptional(array $optionNames)

Alias of {@link setDefined()}.

bool isKnown(string $option)

Alias of {@link isDefined()}.

Details

public OptionsResolver 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

OptionsResolver This instance

Exceptions

AccessException If called from a lazy option or normalizer

public OptionsResolver setDefaults(array $defaults)

Sets a list of default values.

Parameters

array $defaults The default values to set

Return Value

OptionsResolver This instance

Exceptions

AccessException If called from a lazy option or normalizer

public 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

public OptionsResolver setRequired(string|string[] $optionNames)

Marks one or more options as required.

Parameters

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

Return Value

OptionsResolver This instance

Exceptions

AccessException If called from a lazy option or normalizer

public 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

public string[] getRequiredOptions()

Returns the names of all required options.

Return Value

string[] The names of the required options

See also

isRequired()

public 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

public string[] getMissingOptions()

Returns the names of all options missing a default value.

Return Value

string[] The names of the missing options

See also

isMissing()

public OptionsResolver 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

OptionsResolver This instance

Exceptions

AccessException If called from a lazy option or normalizer

public 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

public string[] getDefinedOptions()

Returns the names of all defined options.

Return Value

string[] The names of the defined options

See also

isDefined()

public OptionsResolver 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

OptionsResolver This instance

Exceptions

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

public OptionsResolverInterface setNormalizers(array $normalizers)

Sets normalizers that are applied on resolved options.

The normalizers should be closures with the following signature:

function (Options $options, $value)

The second parameter passed to the closure is the value of the option.

The closure should return the normalized value.

Parameters

array $normalizers An array of closures.

Return Value

OptionsResolverInterface The resolver instance.

public OptionsResolver setAllowedValues(string $option, mixed $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
mixed $allowedValues One or more acceptable values/closures

Return Value

OptionsResolver This instance

Exceptions

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

public OptionsResolver addAllowedValues(string $option, mixed $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
mixed $allowedValues One or more acceptable values/closures

Return Value

OptionsResolver This instance

Exceptions

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

public OptionsResolver setAllowedTypes(string $option, string|string[] $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
string|string[] $allowedTypes One or more accepted types

Return Value

OptionsResolver This instance

Exceptions

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

public OptionsResolver addAllowedTypes(string $option, string|string[] $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
string|string[] $allowedTypes One or more accepted types

Return Value

OptionsResolver This instance

Exceptions

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

public OptionsResolver 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

OptionsResolver This instance

Exceptions

AccessException If called from a lazy option or normalizer

public OptionsResolver clear()

Removes all options.

Return Value

OptionsResolver This instance

Exceptions

AccessException If called from a lazy option or normalizer

public 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 A map of option names to values

Return Value

array The merged and validated options

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

public 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

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

public offsetSet($option, $value)

Not supported.

Parameters

$option
$value

Exceptions

AccessException

public offsetUnset($option)

Not supported.

Parameters

$option

Exceptions

AccessException

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

public set($option, $value)

Alias of {@link setDefault()}.

Parameters

$option
$value

public replace(array $defaults)

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

Parameters

array $defaults

public overload($option, $value)

Alias of {@link setDefault()}.

Parameters

$option
$value

public get($option)

Alias of {@link offsetGet()}.

Parameters

$option

public has($option)

Alias of {@link offsetExists()}.

Parameters

$option

public OptionsResolverInterface replaceDefaults(array $defaultValues)

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

OptionsResolverInterface The resolver instance.

public OptionsResolverInterface setOptional(array $optionNames)

Alias of {@link setDefined()}.

Parameters

array $optionNames A list of option names.

Return Value

OptionsResolverInterface The resolver instance.

public bool isKnown(string $option)

Alias of {@link isDefined()}.

Parameters

string $option The name of the option.

Return Value

bool Whether the option is known.

© 2004–2016 Fabien Potencier
Licensed under the MIT License.
http://api.symfony.com/2.7/Symfony/Component/OptionsResolver/OptionsResolver.html