Refactored OptionsResolver docs to have a better example

[wouterj]

Q	A
Doc fix?	yes
New docs?	no
Applies to	2.1+
Fixed tickets	#2353 (comment)

As requested by @bschussek, I changed the example to a Mailer class. There are only 2 things I don't like:

1. The example under "Default Values that depend on another Option" shows a port setting depending on the host setting. I think it's a really weird example, but I can't think of a better one.
2. I can't find a good example for the replaceDefaults method.

[webmozart]

Thanks again for your work on this! Some feedback below:

The $options property is an instance of :class:Symfony\\Component\\OptionsResolver\\Options

This block is actually misplaced. When you just use resolve(), you never have an Options instance. You pass in an array, you get out an array. You only deal with Options instances in closures.

Next, while adding getters for options is a possibility, I wouldn't recommend it as a default showcase. As we are describing a service, it would make more sense to show a mail() method that accesses these internal options.

Also I would rename setDefaultOptions to configureOptions, since we do much more in here than just default value setting. The fact that it's called setDefaultOptions in the Form component is unfortunate and cannot be changed for now.

The blocks about optional options and default values are a bit misleading. Options with default values are optional too. The documentation suggests that I need to call both which is not true. I would restructure the docs to describe (in this order):

• setDefaults: This is what people will and should use most of the time, because most options are usually optional (hence the name). This method guarantees that option keys will be present in the array returned by resolve so that you don't have to worry about using isset and things like that anymore.
• setRequired: Used in the (rarer) occasion that an option actually has to be set by the user.
• setOptional: Used in the (vary rare) occasion that an option should not be present in the final option array if the user did not pass it. This makes it possible to decide whether a user actually passed an option or not.

When it comes to dependent default values, I'd use the examples "encryption" and "port":

use Symfony\Component\OptionsResolver\Options;

// ...
protected function setDefaultOptions(OptionsResolverInterface $resolver)
{
    // ...

    $resolver->setDefaults(array(
        'encryption' => null,
        'port' => function (Options $options) {
            if ('ssl' === $options['encryption']) {
                return 465;
            }

            return 25;
        },
    ));
}

Here may also be the appropriate place to describe why the options in the closure are an Options instance and not an array.

For the allowed default values, I'd use the example "encryption" again (to avoid introducing another example).

// ...
protected function setDefaultOptions(OptionsResolverInterface $resolver)
{
    // ...

    $resolver->setAllowedValues(array(
        'encryption' => array(null, 'ssl', 'tls'),
    ));
}

The last example about normalizing the host is probably wrong. Host names for mailing usually don't start with 'http://', since the protocol is SMTP, not HTTP. I've scanned the Swiftmailer configuration for a bit but I'm still lacking a better example for the mailer case.

[stof]

This condition looks really weird to me given that you are configuring a mailer. You may want to find a better normalization example

[wouterj]

This actually wasn't ready to merge yet, I haven't had the time to implement @bschussek's suggestions. I'll make a new PR soon to fix those things.

[weaverryan]

Merged! Woot! Minor tweaks at sha: cbb304f - very nice work @wouterj!

[weaverryan]

@wouterj sounds fine! I did miss Bernhard's comment.