[PHP 8.1] Add ReturnTypeWillChange attribute where necessary

I wonder if it is okay to actually add the return typehint to \Drupal\Component\Render\MarkupTrait. I think if you use the trait you should be overriding __jsonSerialize() - no one in contrib does this... http://grep.xnddx.ru/search?text=MarkupTrait&filename=

+++ b/core/lib/Drupal/Core/Session/SessionHandler.php
@@ -46,6 +46,7 @@ public function __construct(RequestStack $request_stack, Connection $connection)
   /**
    * {@inheritdoc}
    */
+  #[\ReturnTypeWillChange]
   public function open($save_path, $name) {
     return TRUE;
   }

Shall we broaden the scope of this issue? I think it might be better to move the session stuff into its own one. And leave the test one to a fix tests on PHP 8.1 issue.

@longwave where the changes reverted? I think it needs new patch and session looks better to split out to separate issue

I've been thinking about the scope here and actually I'm more and more thinking let's add all the #[ReturnTypeWillChange] in one issue and the open issues to add the proper typehints. These annotations are merely comments so I don't think a scope really helps...

Changing the scope and generating the patch from #3220021: [meta] Ensure compatibility of Drupal 9 with PHP 8.1 (as it evolves)

Curious about how to make sure no places are missed, maybe there a way to catch it with static analysis....

@longwave I think we should accept policy first to improve type-hinting, that's why static analysis sounds promising

+++ b/core/lib/Drupal/Core/DependencyInjection/DependencySerializationTrait.php
@@ -64,6 +64,7 @@ public function __sleep() {
   /**
    * {@inheritdoc}
    */
+  #[\ReturnTypeWillChange]
   public function __wakeup() {

This is kinda the odd one out. It's because this trait is used in \Drupal\jsonapi\Exception\UnprocessableHttpEntityException and \Drupal\jsonapi\Exception\EntityAccessDeniedHttpException - I'm not sure that we should be adding : void here in the future...

Re #12 we get testing once we enable PHP 8.1 testing. It doesn't matter if we missing something here. We can't enable PHP 8.1 till we've fixed everything else.

Re D10 - yes we're going to need to add return types for PHP 9. My guess is that we'll see more and more of this in the next PHP 8 minor releases.

Re downstream - if they are not extended or don't care then they can implement the return type otherwise they've have to add the annotation to to be PHP 8.1 compatible. The reason we're doing this is to make downstream code not have to change right away.

I don't think either of the issues added in #14 should block this. This is only adding comments.

Re DependencySerializationTrait - I'm not sure we should be using that on exceptions - as far as our test coverage goes these usages of the trait are not necessary - see #2561915-24: alexpott's test issue

For policy we already have #1158720: Improve text for parameter type hinting in function declaration. However we need a specific follow-up to remove ReturnTypeWillChange from everywhere we've added it probably.

There are several places in the patch where I think we could add the return type hint in Drupal 9 too - it's not different to any other change to @internal code where we don't expect subclassing.

Added a follow-up to determine what we can do in Drupal 9 already - see #3232639: Determine which ReturnTypeWillChange can be fixed in Drupal 9

Committed f06ad93 and pushed to 9.3.x. Thanks!

Feels like a good first step to unlock progress and then go over it with a finer tooth comb