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 useresolve(), 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 amail() method that accesses these internal options.

Also I would renamesetDefaultOptions toconfigureOptions, since we do much more in here than just default value setting. The fact that it's calledsetDefaultOptions 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 byresolve so that you don't have to worry about usingisset 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":

useSymfony\Component\OptionsResolver\Options;// ...protectedfunctionsetDefaultOptions(OptionsResolverInterface$resolver){// ...$resolver->setDefaults(array('encryption' =>null,'port' =>function (Options$options) {if ('ssl' ===$options['encryption']) {return465;            }return25;        },    ));}

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

// ...protectedfunctionsetDefaultOptions(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.

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.

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

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