feature #38996 Remove the default values from setters with a nullable parameter (derrabus, nicolas-grekas)

This PR was merged into the 6.2 branch.

Discussion
----------

Remove the default values from setters with a nullable parameter

| Q             | A
| ------------- | ---
| Branch?       | 6.2
| Bug fix?      | no
| New feature?  | no
| Deprecations? | yes
| Tickets       | N/A
| License       | MIT
| Doc PR        | N/A

Setters with a default value are a bit odd: I want to set a value, but I won't tell you which one!

We do have this kind of setters, like this example from `TokenStorageInterface`:

```php
public function setToken(TokenInterface $token = null);
```

This means that those to calls are equivalent:

```php
$tokenStorage->setToken(null);
$tokenStorage->setToken();
```

The reason for this is actually a php 5 quirk: On php 5, we did not have nullable parameter type declarations – those we added in php 7.1. The only workaround was to declare `null` as default value because then php would accept passing null despite the type declaration demanding an instance of a specific class/interface.

Because the days of php 5 are over, I'd like to change this. Our method signature would then look like this.

```php
public function setToken(?TokenInterface $token);
```

We can do this for interfaces and abstract methods because an implementation may add a default value. Thus, removing the default value from the interface alone is not a BC break.

For the implementations of that interface, this is a different story because removing the default breaks calling code that omits the parameter entirely. This is why for the implementations I trigger a deprecation if the method is called without arguments. This enables us to remove the default in Symfony 6.

This PR performs the suggested changes for `TokenStorageInterface` and `ContainerAwareInterface`, but we have a few more setters like this. But before I continue, I'd like to collect some feedback if this is something you would want to change.

Commits
-------

78803b2962 Remove all "nullable-by-default-value" setters
917ffde141 Remove the default values from setters with a nullable parameter.

Author: nicolas-grekas

Button.php

@@ -83,6 +83,9 @@ public function offsetUnset(mixed $offset): void
 
     public function setParent(FormInterface $parent = null): static
     {
+        if (1 > \func_num_args()) {
+            trigger_deprecation('symfony/form', '6.2', 'Calling "%s()" without any arguments is deprecated, pass null explicitly instead.', __METHOD__);
+        }
         if ($this->submitted) {
             throw new AlreadySubmittedException('You cannot set the parent of a submitted button.');
         }

ButtonBuilder.php

@@ -194,6 +194,10 @@ public function setAttributes(array $attributes): static
      */
     public function setDataMapper(DataMapperInterface $dataMapper = null): static
     {
+        if (1 > \func_num_args()) {
+            trigger_deprecation('symfony/form', '6.2', 'Calling "%s()" without any arguments is deprecated, pass null explicitly instead.', __METHOD__);
+        }
+
         throw new BadMethodCallException('Buttons do not support data mappers.');
     }
 

CHANGELOG.md

@@ -4,8 +4,11 @@ CHANGELOG
 6.2
 ---
 
-* Allow passing `TranslatableInterface` objects to the `ChoiceView` label
-* Allow passing `TranslatableInterface` objects to the `help` option
+ * Allow passing `TranslatableInterface` objects to the `ChoiceView` label
+ * Allow passing `TranslatableInterface` objects to the `help` option
+ * Deprecate calling `Button/Form::setParent()`, `ButtonBuilder/FormConfigBuilder::setDataMapper()`, `TransformationFailedException::setInvalidMessage()` without arguments
+ * Change the signature of `FormConfigBuilderInterface::setDataMapper()` to `setDataMapper(?DataMapperInterface)`
+ * Change the signature of `FormInterface::setParent()` to `setParent(?self)`
 
 6.1
 ---

Exception/TransformationFailedException.php

@@ -36,6 +36,9 @@ public function __construct(string $message = '', int $code = 0, \Throwable $pre
      */
     public function setInvalidMessage(string $invalidMessage = null, array $invalidMessageParameters = []): void
     {
+        if (1 > \func_num_args()) {
+            trigger_deprecation('symfony/form', '6.2', 'Calling "%s()" without any arguments is deprecated, pass null explicitly instead.', __METHOD__);
+        }
         $this->invalidMessage = $invalidMessage;
         $this->invalidMessageParameters = $invalidMessageParameters;
     }

Form.php

@@ -220,6 +220,10 @@ public function isDisabled(): bool
 
     public function setParent(FormInterface $parent = null): static
     {
+        if (1 > \func_num_args()) {
+            trigger_deprecation('symfony/form', '6.2', 'Calling "%s()" without any arguments is deprecated, pass null explicitly instead.', __METHOD__);
+        }
+
         if ($this->submitted) {
             throw new AlreadySubmittedException('You cannot set the parent of a submitted form.');
         }

FormConfigBuilder.php

@@ -340,6 +340,9 @@ public function setAttributes(array $attributes): static
 
     public function setDataMapper(DataMapperInterface $dataMapper = null): static
     {
+        if (1 > \func_num_args()) {
+            trigger_deprecation('symfony/form', '6.2', 'Calling "%s()" without any arguments is deprecated, pass null explicitly instead.', __METHOD__);
+        }
         if ($this->locked) {
             throw new BadMethodCallException('FormConfigBuilder methods cannot be accessed anymore once the builder is turned into a FormConfigInterface instance.');
         }

FormConfigBuilderInterface.php

@@ -100,7 +100,7 @@ public function setAttributes(array $attributes): static;
      *
      * @return $this
      */
-    public function setDataMapper(DataMapperInterface $dataMapper = null): static;
+    public function setDataMapper(?DataMapperInterface $dataMapper): static;
 
     /**
      * Sets whether the form is disabled.

FormInterface.php

@@ -34,7 +34,7 @@ interface FormInterface extends \ArrayAccess, \Traversable, \Countable
      * @throws Exception\LogicException            when trying to set a parent for a form with
      *                                             an empty name
      */
-    public function setParent(self $parent = null): static;
+    public function setParent(?self $parent): static;
 
     /**
      * Returns the parent form.