minor #2228 Improve deprecations DX (GuilhemN)

This PR was merged into the 2.x branch.

Discussion
----------

Improve deprecations DX

While trying to add support for FOSRestBundle 3.x to NelmioApiDocBundle, I found a few deprecations that could be improved:
- the deprecations from the routing services don't specify how to solve them, I added a reference to a config field
- deprecations of suboptions of `fos_rest.exception` even if `exception` is not enabled. I solved it by using `validate` instead of `defaultValue` + `beforeNormalization` at the level of `exception`.

Commits
-------

37fa934 Improve deprecations DX

DependencyInjection/Configuration.php

@@ -463,44 +463,37 @@ private function addExceptionSection(ArrayNodeDefinition $rootNode)
                     ->fixXmlConfig('message', 'messages')
                     ->addDefaultsIfNotSet()
                     ->canBeEnabled()
+                    ->validate()
+                      ->always()
+                      ->then(function ($v) {
+                          if (!$v['enabled']) {
+                            return $v;
+                          }
+
+                          if ($v['exception_listener']) {
+                              @trigger_error('Enabling the "fos_rest.exception.exception_listener" option is deprecated since FOSRestBundle 2.8.', E_USER_DEPRECATED);
+                          }
+                          if ($v['serialize_exceptions']) {
+                              @trigger_error('Enabling the "fos_rest.exception.serialize_exceptions" option is deprecated since FOSRestBundle 2.8.', E_USER_DEPRECATED);
+                          }
+
+                          return $v;
+                      })
+                    ->end()
                     ->children()
                         ->booleanNode('map_exception_codes')
                             ->defaultFalse()
                             ->info('Enables an event listener that maps exception codes to response status codes based on the map configured with the "fos_rest.exception.codes" option.')
                         ->end()
                         ->booleanNode('exception_listener')
-                            ->defaultValue(function () {
-                                @trigger_error('Enabling the "fos_rest.exception.exception_listener" option is deprecated since FOSRestBundle 2.8.', E_USER_DEPRECATED);
-
-                                return true;
-                            })
-                            ->beforeNormalization()
-                                ->ifTrue()
-                                ->then(function ($v) {
-                                    @trigger_error('Enabling the "fos_rest.exception.exception_listener" option is deprecated since FOSRestBundle 2.8.', E_USER_DEPRECATED);
-
-                                    return $v;
-                                })
-                            ->end()
+                            ->defaultTrue()
                         ->end()
                         ->scalarNode('exception_controller')
                             ->defaultNull()
                             ->setDeprecated('The "%path%.%node%" option is deprecated since FOSRestBundle 2.8.')
                         ->end()
                         ->booleanNode('serialize_exceptions')
-                            ->defaultValue(function () {
-                                @trigger_error('Enabling the "fos_rest.exception.serialize_exceptions" option is deprecated since FOSRestBundle 2.8.', E_USER_DEPRECATED);
-
-                                return true;
-                            })
-                            ->beforeNormalization()
-                                ->ifTrue()
-                                ->then(function ($v) {
-                                    @trigger_error('Enabling the "fos_rest.exception.serialize_exceptions" option is deprecated since FOSRestBundle 2.8.', E_USER_DEPRECATED);
-
-                                    return $v;
-                                })
-                            ->end()
+                            ->defaultTrue()
                         ->end()
                         ->enumNode('flatten_exception_format')
                             ->defaultValue('legacy')

Resources/config/routing.xml

@@ -10,18 +10,18 @@
             <argument type="service" id="file_locator" />
             <argument type="service" id="fos_rest.routing.loader.processor" />
             <tag name="routing.loader" />
-            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8.</deprecated>
+            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8. You can disable it by setting the config `fos_rest.routing_loader.enabled` to `false`.</deprecated>
         </service>
 
         <service id="fos_rest.routing.loader.controller" class="FOS\RestBundle\Routing\Loader\RestRouteLoader" public="false">
             <argument type="service" id="service_container" />
             <argument type="service" id="file_locator" />
             <tag name="routing.loader" />
-            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8.</deprecated>
+            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8. You can disable it by setting the config `fos_rest.routing_loader.enabled` to `false`.</deprecated>
         </service>
 
         <service id="fos_rest.routing.loader.processor" class="FOS\RestBundle\Routing\Loader\RestRouteProcessor" public="false">
-            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8.</deprecated>
+            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8. You can disable it by setting the config `fos_rest.routing_loader.enabled` to `false`.</deprecated>
         </service>
 
         <service id="fos_rest.routing.loader.yaml_collection" class="FOS\RestBundle\Routing\Loader\RestYamlCollectionLoader" public="false">
@@ -31,7 +31,7 @@
             <argument type="collection" /> <!-- formats -->
             <argument /> <!-- default format -->
             <tag name="routing.loader" />
-            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8.</deprecated>
+            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8. You can disable it by setting the config `fos_rest.routing_loader.enabled` to `false`.</deprecated>
         </service>
 
         <service id="fos_rest.routing.loader.xml_collection" class="FOS\RestBundle\Routing\Loader\RestXmlCollectionLoader" public="false">
@@ -41,7 +41,7 @@
             <argument type="collection" /> <!-- formats -->
             <argument /> <!-- default format -->
             <tag name="routing.loader" />
-            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8.</deprecated>
+            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8. You can disable it by setting the config `fos_rest.routing_loader.enabled` to `false`.</deprecated>
         </service>
 
         <service id="fos_rest.routing.loader.reader.controller" class="FOS\RestBundle\Routing\Loader\Reader\RestControllerReader" public="false">
@@ -57,7 +57,7 @@
             <argument /> <!-- include format -->
             <argument type="collection" /> <!-- formats -->
             <argument /> <!-- prefix_methods bool -->
-            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8.</deprecated>
+            <deprecated>The %service_id% service is deprecated since FOSRestBundle 2.8. You can disable it by setting the config `fos_rest.routing_loader.enabled` to `false`.</deprecated>
         </service>
     </services>