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

CHANGELOG.md

@@ -10,6 +10,7 @@ CHANGELOG
  * Add `absolute_uri` option to surrogate fragment renderers
  * Add `ValueResolverInterface` and deprecate `ArgumentValueResolverInterface`
  * Add argument `$reflector` to `ArgumentResolverInterface` and `ArgumentMetadataFactoryInterface`
+ * Deprecate calling `ConfigDataCollector::setKernel()`, `RouterListener::setCurrentRequest()` without arguments
 
 6.1
 ---

DataCollector/ConfigDataCollector.php

@@ -31,6 +31,10 @@ class ConfigDataCollector extends DataCollector implements LateDataCollectorInte
      */
     public function setKernel(KernelInterface $kernel = null)
     {
+        if (1 > \func_num_args()) {
+            trigger_deprecation('symfony/http-kernel', '6.2', 'Calling "%s()" without any arguments is deprecated, pass null explicitly instead.', __METHOD__);
+        }
+
         $this->kernel = $kernel;
     }
 

EventListener/RouterListener.php

@@ -68,7 +68,7 @@ public function __construct(UrlMatcherInterface|RequestMatcherInterface $matcher
         $this->debug = $debug;
     }
 
-    private function setCurrentRequest(Request $request = null)
+    private function setCurrentRequest(?Request $request)
     {
         if (null !== $request) {
             try {

HttpCache/ResponseCacheStrategy.php

@@ -110,7 +110,7 @@ public function update(Response $response)
         $response->headers->set('Age', $this->age);
 
         if ($this->isNotCacheableResponseEmbedded) {
-            $response->setLastModified();
+            $response->setLastModified(null);
 
             if ($this->flagDirectives['no-store']) {
                 $response->headers->set('Cache-Control', 'no-cache, no-store, must-revalidate');