Editor PHP 2.4.0

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

Table of Contents

Interfaces

Options
Contains 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.

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

getDefinedOptions()

Returns the names of all defined options.

public getDefinedOptions() : array<string|int, string>
Tags
see
isDefined()
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>
Tags
see
isRequired()
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

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
Tags
throws
AccessException

If accessing this method outside of

see
ArrayAccess::offsetExists()
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)

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

offsetSet()

Not supported.

public offsetSet(mixed $option, mixed $value) : void
Parameters
$option : mixed
$value : mixed
Tags
throws
AccessException

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

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

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

If called from a lazy option or normalizer

Return values
$this

setDefaults()

public setDefaults(array<string|int, mixed> $defaults) : $this
Parameters
$defaults : array<string|int, mixed>
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, 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
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
$normalizer : Closure
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 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results