[DoctrineBridge] Allow to ignore specific nullable fields in UniqueEnti…

[nicolas-grekas]

Q	A
Feature PR	symfony/symfony#49293
PR author(s)	@VincentLanglet
Merged in	6.3

We created this issue to not forget to document this new feature. We would really appreciate if you can help us with this task. If you are not sure how to do it, please ask us and we will help you.

To fix this issue, please create a PR against the 6.3 branch in the symfony-docs repository.

Thank you! 😃

[nicolas-grekas]

For inspiration:

UniqueEntity Constraint
=======================

The ``UniqueEntity`` constraint is used to ensure that one or multiple fields or properties of an entity in a Doctrine
mapping are unique. The uniqueness is checked upon validation and a violation is generated if the constraints are not met.

Ignore Null Values on Specific Fields
--------------------------------------

As of Symfony 6.3, the ``UniqueEntity`` constraint allows you to ignore null values on specific fields when checking for
uniqueness. This feature can be helpful when you want to validate the uniqueness of a combination of fields, but want to
exclude combinations where one or more of the fields are null.

Usage
-----

You can ignore null values by providing a string or an array of field names to the ``ignoreNull`` option:

.. code-block:: php

    use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;

    #[UniqueEntity(
         fields: ['name', 'email'],
         ignoreNull: 'name',
    )]

In the example above, null values for the "name" field will be ignored when checking for uniqueness.

Similarly, you can ignore null values for multiple fields:

.. code-block:: php

    #[UniqueEntity(
         fields: ['name', 'email'],
         ignoreNull: ['name', 'email'],
    )]

In this case, null values for both the "name" and "email" fields will be ignored.

Note
----

If you enable ``ignoreNull`` for a field, uniqueness checks that would normally consider null values will skip these
values. This means that if you have multiple entities with null values for a field marked with ``ignoreNull``, they will
not be considered non-unique.

Caution
-------

Be careful when using ``ignoreNull`` on fields that are part of a unique index in your database. Ignoring null values
in the ``UniqueEntity`` constraint but not in your database could lead to insertion errors if your application attempts
to persist entities that the ``UniqueEntity`` constraint considers valid.

[javiereguiluz]

Fixed in #18335.