@@ -634,6 +634,43 @@ let you find out which options are defined::
634634 }
635635 }
636636
637+ Deprecating the Option
638+ ~~~~~~~~~~~~~~~~~~~~~~
639+
640+ Once an option is outdated or you decided not to maintain it anymore, you can deprecate it
641+ using the:method: `Symfony\\ Component\\ OptionsResolver\\ OptionsResolver::setDeprecated `
642+ method::
643+
644+ $resolver
645+ ->setDefined(array('hostname', 'host'))
646+ // this outputs the following generic deprecation message:
647+ // The option "hostname" is deprecated.
648+ ->setDeprecated('hostname')
649+
650+ // you can also pass a custom deprecation message
651+ ->setDeprecated('hostname', 'The option "hostname" is deprecated, use "host" instead.')
652+ ;
653+
654+ Instead of passing the message, you may also pass a closure which returns
655+ a string (the deprecation message) or an empty string to ignore the deprecation.
656+ This closure is specially useful to deprecate allowed types or values of the
657+ defined option::
658+
659+ $resolver
660+ ->setDefault('port', null)
661+ ->setAllowedTypes('port', array('null', 'int'))
662+ ->setDeprecated('port', function ($value) {
663+ if (null === $value) {
664+ return 'Passing "null" to option "port" is deprecated, pass an integer instead.';
665+ }
666+
667+ return '';
668+ })
669+ ;
670+
671+ This closure receives as argument the value of the option after validating it
672+ and before normalize it when the option is being resolved.
673+
637674Performance Tweaks
638675~~~~~~~~~~~~~~~~~~
639676