Add separate issue

config.xsd

@@ -325,6 +325,7 @@
             <xs:element name="LoopInvalidation" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="MethodSignatureMismatch" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="MethodSignatureMustOmitReturnType" type="IssueHandlerType" minOccurs="0" />
+            <xs:element name="MethodSignatureMustProvideReturnType" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="MismatchingDocblockParamType" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="MismatchingDocblockPropertyType" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="MismatchingDocblockReturnType" type="IssueHandlerType" minOccurs="0" />

docs/running_psalm/error_levels.md

@@ -56,6 +56,7 @@ Level 5 and above allows a more non-verifiable code, and higher levels are even
  - [InvalidThrow](issues/InvalidThrow.md)
  - [LoopInvalidation](issues/LoopInvalidation.md)
  - [MethodSignatureMustOmitReturnType](issues/MethodSignatureMustOmitReturnType.md)
+ - [MethodSignatureMustProvideReturnType](issues/MethodSignatureMustProvideReturnType.md)
  - [MissingDependency](issues/MissingDependency.md)
  - [MissingFile](issues/MissingFile.md)
  - [MissingImmutableAnnotation](issues/MissingImmutableAnnotation.md)

docs/running_psalm/issues.md

@@ -99,6 +99,7 @@
  - [LoopInvalidation](issues/LoopInvalidation.md)
  - [MethodSignatureMismatch](issues/MethodSignatureMismatch.md)
  - [MethodSignatureMustOmitReturnType](issues/MethodSignatureMustOmitReturnType.md)
+ - [MethodSignatureMustProvideReturnType](issues/MethodSignatureMustProvideReturnType.md)
  - [MismatchingDocblockParamType](issues/MismatchingDocblockParamType.md)
  - [MismatchingDocblockPropertyType](issues/MismatchingDocblockPropertyType.md)
  - [MismatchingDocblockReturnType](issues/MismatchingDocblockReturnType.md)

docs/running_psalm/issues/MethodSignatureMustProvideReturnType.md

@@ -0,0 +1,48 @@
+# MethodSignatureMustProvideReturnType
+
+In PHP 8.1+, [most non-final internal methods now require overriding methods to declare a compatible return type, otherwise a deprecated notice is emitted during inheritance validation](https://www.php.net/manual/en/migration81.incompatible.php#migration81.incompatible.core.type-compatibility-internal).  
+
+This issue is emitted when a method overriding a native method is defined without a return type.  
+
+
+```php
+<?php
+
+class A implements JsonSerializable {
+    public function jsonSerialize() {
+        return random_int(0, 1) ? 'test' : 123;
+    }
+}
+```
+
+Fix by specifying the correct typehint:  
+
+```php
+<?php
+
+class A implements JsonSerializable {
+    public function jsonSerialize(): string|int {
+        return random_int(0, 1) ? 'test' : 123;
+    }
+}
+```
+
+In case the return type cannot be declared for an overriding method due to PHP cross-version compatibility concerns, a `#[ReturnTypeWillChange]` attribute can be added to silence the PHP deprecation notice and Psalm issue. 
+
+```php
+<?php
+
+use ReturnTypeWillChange;
+
+class A implements JsonSerializable {
+    /**
+     * TODO: Remove this attribute once PHP 7 support is dropped.
+     * 
+     * @return "test"|123
+     */
+    #[ReturnTypeWillChange]
+    public function jsonSerialize() {
+        return random_int(0, 1) ? 'test' : 123;
+    }
+}
+```

src/Psalm/Internal/Analyzer/MethodComparator.php

@@ -21,6 +21,7 @@
 use Psalm\Issue\ImplementedReturnTypeMismatch;
 use Psalm\Issue\LessSpecificImplementedReturnType;
 use Psalm\Issue\MethodSignatureMismatch;
+use Psalm\Issue\MethodSignatureMustProvideReturnType;
 use Psalm\Issue\MissingImmutableAnnotation;
 use Psalm\Issue\MoreSpecificImplementedParamType;
 use Psalm\Issue\OverriddenMethodAccess;
@@ -130,8 +131,8 @@ function (AttributeStorage $s) {
             )
         ) {
             IssueBuffer::maybeAdd(
-                new MethodSignatureMismatch(
-                    'Method ' . $cased_implementer_method_id . ' is missing a return type signature!',
+                new MethodSignatureMustProvideReturnType(
+                    'Method ' . $cased_implementer_method_id . ' must have a return type signature!',
                     $implementer_method_storage->location ?: $code_location
                 ),
                 $suppressed_issues + $implementer_classlike_storage->suppressed_issues

src/Psalm/Issue/MethodSignatureMustProvideReturnType.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Psalm\Issue;
+
+class MethodSignatureMustProvideReturnType extends CodeIssue
+{
+    public const ERROR_LEVEL = -1;
+    public const SHORTCODE = 282;
+}

tests/MethodSignatureTest.php

@@ -1582,7 +1582,7 @@ public function test() {
                         }
                     }
                 ',
-                'error_message' => 'MethodSignatureMismatch',
+                'error_message' => 'MethodSignatureMustProvideReturnType',
                 [],
                 false,
                 '8.0'
@@ -1595,7 +1595,7 @@ public function jsonSerialize() {
                         }
                     }
                 ',
-                'error_message' => 'MethodSignatureMismatch',
+                'error_message' => 'MethodSignatureMustProvideReturnType',
                 [],
                 false,
                 '8.1'