I'm not really happy seeing this being static, what's the argument against $options->resolve($defaults)?

@iltar having to instantiate a resolver to resolver simple defaults makes it much slower, and also more complex to use. The static call is an enhanced version of options = array_merge($defaults, $options), allowing to validate options instead of just bring defaults in. AFAIK, nobody has ever complained that merging the defaults in your methods is using procedural code generally.

And as you can see, the usage of an Options instance allows to provide extension points for the definition of the defaults (which is what the component aims to solve for forms)

@stof in both examples provided, the argument passed to Options::resolve() is an instance of Options. Following the examples, I prefer the api listed below as it's less thinking and makes it more intuitive .

// Basic option resolving
$options = $options->resolve(array(
    'choices' = array(),
));

// More advanced option configuration
$defaults = new Options();
$defaults['choices'] = array();
$defaults->setRequired('em');

$options = $options->resolve($defaults);

// Form component example (3.0)
public function setDefaultOptions(Options $options) {
    $options['choices'] = array();

    $options->setRequired('em');
}

@iltar the basic usage in @webmozart's comment does not require you to build an object. And $options is the array of values provided by the user of your code

@stof so if I understand it correctly, the idea is to also allow an array. In that case, this is a good solution. I'm still not in favor of static methods in my code, but I supposed this will be behind the scenes. What will be the case when someone implements their own Options implementation?

So does this also make it possible to use nested options as described in #4833? :)

@iltar As @stof said, Options::resolve($options, $defaults) is an enhanced version of array_replace($defaults, $options). This is very low-level code - a static call really shouldn't matter there. Being that low-level, own Options implementations are not anticipated nor supported.

@sstok Not yet.

I finished the PR now.

I'm currently adapting the PR so that we can close #10616. I'm also preparing the implementation of #4833 in 2.7+ without breaking BC. I need some feedback to complete that.

In 2.6, I changed Options to allow for two different resolving syntaxes:

The simple syntax without any objects, designed for high performance (array_replace() on steroids):

public function __construct(array $options = array())
{
    Options::validateRequired($options, 'em');
    Options::validateTypes($options, array(
        'em' => 'Doctrine\ORM\EntityManager',
    ));

    $this->options = Options::resolve($options, array(
        'class' => null,
        'query_builder' => null,
    ));
}

And the object-based syntax with the flexibility that we know of the OptionsResolver (lazy options, normalization...):

public function __construct(array $options = array())
{
    $defaults = new Options();
    $defaults['class'] = null;
    $defaults['query_builder'] = null;
    $defaults->setRequired('em');
    $defaults->setAllowedTypes(array(
        'em' => 'Doctrine\ORM\EntityManager',
    ));

    $this->options = Options::resolve($options, $defaults);
}

My question to you is: Would any of you actually use the first mentioned, static API? Or should we remove it and make resolve() an instance method usable like this:

public function __construct(array $options = array())
{
    $defaults = new Options();
    // ...

    $this->options = $defaults->resolve($options);
}

The static method syntax was introduced in 2.6 so it can be removed now (or at any time before the first RC version.)

By the way, I'm all for removing the static API.

👍 for removing static API

same, +1 for removing static api

Less is more, and I'm usually against static. I would definitely use the last example.

Good, thanks for the feedback!

I updated the PR and the above description now.

The documentation is adapted now: https://github.com/webmozart/symfony-docs/blob/issue11705/components/options_resolver.rst

With the new methods introduced, it would probably be a good time to fix #10585. So its not wrong again.

Also what I always find irritating is the magic of defining lazy options.
There is a huge difference between

$options->set('name', function (Options $options, $previousValue) {
});

and

$options->set('name', function ($options, $previousValue) {
});

which is non-obvious. Maybe there should be different methods for defining plain options and lazy avaluated options?

Also I think Options:resolve should not clone. The OptionsResolver should only clone the options when calling resolve. The semantics are different. It makes sense that one can use one resolver to call resolve multiple times. But for options it makes things so conplicated and confusing. E.g. it's not possible to call the following which is strange from a users perspective. Or am I missing something?

$options = new Options();
$options['foo'] = 'bar';
$options->resolve(array());
echo $options['foo'];

@Tobion The "problem" about using a separate method for lazy options is that it then isn't obvious anymore how set() and - let's call it - setLazy() interact:

$options['foo'] = 'bar';
$options->setLazy('foo', function (Options $options) {
    return 'dynamic';
});
$options['foo'] = 'baz';

I personally don't find it very clear what the value of the 'foo' option is at the different points in time. With:

$options['foo'] = 'bar';
$options['foo'] = function (Options $options) {
    return 'dynamic';
};
$options['foo'] = 'baz';

it's clear that we are always performing the same set operation. Obviously I'm biased here.

About resolve(): The point of that method is not to change the state of the object, but to resolve the passed options:

$options = new Options();
// ...
$resolvedOptions = $options->resolve($passedOptions);
echo $resolvedOptions['foo'];

From the user POV, it seems confusing to me if resolve() on the one hand turns the input into some output, and on the other hand modifies the internal state of the instance, making it unusable for further resolve() calls.

I'll look into fixing #10585 tomorrow, thanks for mentioning that.

Why should it be a bc break if you do Options extends OptionsInterface and just deprecate Options?

They can be called (BC), but it's true that they are not part of the interface.

It basically forbids these use-cases. But I'm not sure if there are use-cases for options that depend on the definition.

Why deprecate OptionsResolverInterface?

OptionsResolver is a low-level utility which is instantiated in the same class that it is used in most of the time. Interfaces, on the other hand, are contracts helping different classes/components to communicate. What's the point in having an interface for a class which is not supposed to be shared?

It basically forbids these use-cases.

That's good, because these methods are deprecated. The methods can be called, but they shouldn't.

Why should it be a bc break if you do Options extends OptionsInterface and just deprecate Options?

That's a possibility. However this also makes the definition of lazy options unnecessarily longer (and that definition is the sole purpose of the interface's existence):

$resolver->setDefault('choices', function (OptionsInterface $options) {
});

I'd rather make Options an empty class if you insist on the "Interface" suffix.

The PR description, documentation, CHANGELOG and UPGRADE-2.6 files are up to date now.

Please just merge it before it gets reworked again ;)

@Tobion @fabpot I'd like to have your +1 first

Apart from this #12156 (comment) typo 👍

👍

Just a small detail but, what will happen with FormTypeInterface and AbstractType in 2.6? Will they stay like this? public function setDefaultOptions(OptionsResolverInterface $resolver);

Based on the PR I noticed that it should be 100% BC for forms, but I think this should be well documented as BC break for 3.0.

Will they stay like this?

Yes.

Why deprecate OptionsResolverInterface?

OptionsResolver is a low-level utility which is instantiated in the same class that it is used in most of the time. Interfaces, on the other hand, are contracts helping different classes/components to communicate. What's the point in having an interface for a class which is not supposed to be shared?

@webmozart Form types are a good example where you pass the option resolver around to other classes, to configure it. So maybe we should not deprecate the interface ?
On the other hand, it is true that providing a different implementation probably does not make any sense.