Merge branch '4.2' into 4.3

* 4.2:
  Updated Symfony Contracts package names and installation
  Update serializer.rst: deprecate the setCallbacks

Author: javiereguiluz

components/contracts.rst

@@ -12,9 +12,16 @@ The Contracts Component
 Installation
 ------------
 
+Contracts are provided as separate packages, so you can install only the ones
+your projects really need:
+
 .. code-block:: terminal
 
-    $ composer require symfony/contracts
+    $ composer require symfony/cache-contracts
+    $ composer require symfony/event-dispatcher-contracts
+    $ composer require symfony/http-client-contracts
+    $ composer require symfony/service-contracts
+    $ composer require symfony/translation-contracts
 
 .. include:: /components/require_autoload.rst.inc
 
@@ -45,15 +52,15 @@ Design Principles
 * Contracts must be backward compatible with existing Symfony components.
 
 Packages that implement specific contracts should list them in the ``provide``
-section of their ``composer.json`` file, using the
-``symfony/*-contracts-implementation`` convention. For example:
+section of their ``composer.json`` file, using the ``symfony/*-implementation``
+convention. For example:
 
 .. code-block:: javascript
 
     {
         "...": "...",
         "provide": {
-            "symfony/cache-contracts-implementation": "1.0"
+            "symfony/cache-implementation": "1.0"
         }
     }
 
@@ -68,23 +75,4 @@ However, PHP-FIG has different goals and different processes. Symfony Contracts
 focuses  on providing abstractions that are useful on their own while still
 compatible with implementations provided by Symfony.
 
-Why Isn't this Package Split into Several Packages?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Putting all interfaces in one package eases discoverability and dependency
-management. Instead of dealing with a myriad of small packages and the
-corresponding matrix of versions, you only deal with one package and one
-version. Also when using IDE autocompletion or reading the source code, it makes
-it easier to figure out which contracts are provided.
-
-There are two downsides to this approach:
-
-* You may have unused files in your ``vendor/`` directory. This has no impact in
-  practice because the file sizes are very small and there is no performance
-  overhead at all since they are never loaded.
-* In the future, it will be impossible to use two different sub-namespaces in
-  different major versions of the package. However, this package follows the
-  :doc:`Symfony BC + deprecation </contributing/code/bc>` policies, with an
-  additional restriction to never remove deprecated interfaces.
-
 .. _`PHP-FIG`: https://www.php-fig.org/

components/serializer.rst

@@ -639,6 +639,12 @@ and ``remove``.
 Using Callbacks to Serialize Properties with Object Instances
 -------------------------------------------------------------
 
+.. deprecated:: 4.2
+
+    The :method:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNormalizer::setCallbacks`
+    method is deprecated since Symfony 4.2. Use the ``callbacks``
+    key of the context instead.
+
 When serializing, you can set a callback to format a specific object property::
 
     use App\Model\Person;
@@ -647,14 +653,19 @@ When serializing, you can set a callback to format a specific object property::
     use Symfony\Component\Serializer\Serializer;
 
     $encoder = new JsonEncoder();
-    $normalizer = new GetSetMethodNormalizer();
 
     // all callback parameters are optional (you can omit the ones you don't use)
     $callback = function ($innerObject, $outerObject, string $attributeName, string $format = null, array $context = []) {
         return $innerObject instanceof \DateTime ? $innerObject->format(\DateTime::ISO8601) : '';
     };
 
-    $normalizer->setCallbacks(['createdAt' => $callback]);
+    $defaultContext = [
+        AbstractNormalizer::CALLBACKS => [
+            'createdAt' => $callback,
+        ],
+    ];
+    
+    $normalizer = new GetSetMethodNormalizer(null, null, null, null, null, $defaultContext);
 
     $serializer = new Serializer([$normalizer], [$encoder]);