Merge branch '4.2'

* 4.2:
  Documented the Contracts component
  Documented the LoggerAwareInterface autoconfiguration
  Fix format by removing underscore
  Added a note about UniqueEntity and collections
  Added a note about PHPUnit setLocale() method

Author: javiereguiluz

components/contracts.rst

@@ -0,0 +1,90 @@
+.. index::
+   single: Contracts
+   single: Components; Contracts
+
+The Contracts Component
+=======================
+
+    The Contracts component provides a set of abstractions extracted out of the
+    Symfony components. They can be used to build on semantics that the Symfony
+    components proved useful - and that already have battle-tested implementations.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/contracts
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+The abstractions in this package are useful to achieve loose coupling and
+interoperability. By using the provided interfaces as type hints, you are able
+to reuse any implementations that match their contracts. It could be a Symfony
+component, or another package provided by the PHP community at large.
+
+Depending on their semantics, some interfaces can be combined with
+:doc:`autowiring </service_container/autowiring>` to seamlessly inject a service
+in your classes.
+
+Others might be useful as labeling interfaces, to hint about a specific behavior
+that can be enabled when using :ref:`autoconfiguration <services-autoconfigure>`
+or manual :doc:`service tagging </service_container/tags>` (or any other means
+provided by your framework.)
+
+Design Principles
+-----------------
+
+* Contracts are split by domain, each into their own sub-namespaces;
+* Contracts are small and consistent sets of PHP interfaces, traits, normative
+  docblocks and reference test suites when applicable, ...;
+* Contracts must have a proven implementation to enter this repository;
+* 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:
+
+.. code-block:: javascript
+
+    {
+        "...": "...",
+        "provide": {
+            "symfony/cache-contracts-implementation": "1.0"
+        }
+    }
+
+Frequently Asked Questions
+--------------------------
+
+How Is this Different From PHP-FIG's PSRs?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When applicable, the provided contracts are built on top of `PHP-FIG`_'s PSRs.
+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/phpunit_bridge.rst

@@ -10,7 +10,8 @@ The PHPUnit Bridge
 
 It comes with the following features:
 
-* Forces the tests to use a consistent locale (``C``);
+* Forces the tests to use a consistent locale (``C``) (if you create
+  locale-sensitive tests, use PHPUnit's ``setLocale()`` method);
 
 * Auto-register ``class_exists`` to load Doctrine annotations (when used);
 

logging.rst

@@ -338,6 +338,16 @@ option of your handler to ``rotating_file``:
 Using a Logger inside a Service
 -------------------------------
 
+If your application uses :ref:`service autoconfiguration <services-autoconfigure>`,
+any service whose class implements ``Psr\Log\LoggerAwareInterface`` will
+receive a call to its method ``setLogger()`` with the default logger service
+passed as a service.
+
+.. versionadded:: 4.2
+
+    The automatic call to ``setLogger()`` when implementing ``LoggerAwareInterface``
+    was introduced in Symfony 4.2.
+
 If you want to use in your own services a pre-configured logger which uses a
 specific channel (``app`` by default), use the ``monolog.logger`` tag  with the
 ``channel`` property as explained in the

messenger.rst

@@ -437,7 +437,7 @@ for each bus looks like this:
 #. ``logging`` middleware. Responsible for logging the beginning and the end of the
    message within the bus;
 
-#. _Your own collection of middleware_;
+#. Your own collection of middleware_;
 
 #. ``send_message`` middleware. Will route the messages you configured to their
    corresponding sender and stop the middleware chain;

reference/constraints/UniqueEntity.rst

@@ -115,6 +115,12 @@ between all of the constraints in your user table:
     this validation has passed and before this entity is actually persisted in
     the database.
 
+.. caution::
+
+    This constraint cannot deal with duplicates found in a collection of items
+    that haven't been persisted as entities yet. You'll need to create your own
+    validator to handle that case.
+
 Options
 -------