Align PHPDoc @return annotations with PHP 8.0 and 8.1 behavior, updating descriptions for consistency with official documentation.

Author: isfedorov

Core/Core.php

@@ -215,7 +215,7 @@ function str_increment(string $string): string {}
  * @removed 8.0
  */
 #[Deprecated(reason: "Use a foreach loop instead", since: "7.2")]
-function each(&$array): array {}
+function each(&$array): array|false {}
 
 /**
  * Sets which PHP errors are reported

Phar/Phar.php

@@ -2278,7 +2278,6 @@ public function isCRCChecked(): bool {}
      * </p>
      * @return void No value is returned.
      */
-    #[LanguageLevelTypeAware(['8.0' => 'static|null'], default: '')]
     #[TentativeType]
     public function setMetadata(#[LanguageLevelTypeAware(['8.0' => 'mixed'], default: '')] $metadata): void {}
 }

Reflection/ReflectionFunction.php

@@ -99,7 +99,8 @@ public function invokeArgs(array $args): mixed {}
      * Returns a dynamically created closure for the function
      *
      * @link https://php.net/manual/en/reflectionfunction.getclosure.php
-     * @return Closure|null Returns {@see Closure} or {@see null} in case of an error.
+     * @return Closure Returns a {@see Closure}.
+     * Prior to PHP 8.1, {@see null} was returned in case of an error.
      */
     #[Pure]
     #[TentativeType]

Reflection/ReflectionParameter.php

@@ -81,8 +81,8 @@ public function isPassedByReference(): bool {}
      * Returns whether this parameter can be passed by value
      *
      * @link https://php.net/manual/en/reflectionparameter.canbepassedbyvalue.php
-     * @return bool|null {@see true} if the parameter can be passed by value, {@see false} otherwise.
-     * Returns {@see null} in case of an error.
+     * @return bool {@see true} if the parameter can be passed by value, {@see false} otherwise.
+     * Prior to PHP 8.1, {@see null} was returned in case of an error.
      * @since 5.4
      */
     #[TentativeType]
@@ -168,8 +168,8 @@ public function isArray(): bool {}
      * Returns whether parameter MUST be callable
      *
      * @link https://php.net/manual/en/reflectionparameter.iscallable.php
-     * @return bool|null Returns {@see true} if the parameter is callable, {@see false}
-     * if it is not or {@see null} on failure.
+     * @return bool Returns {@see true} if the parameter is callable, {@see false} if it is not.
+     * Prior to PHP 8.1, {@see null} was returned on failure.
      * @since 5.4
      * @see ReflectionParameter::getType()
      */

SPL/SPL_c1.php

@@ -918,7 +918,7 @@ public function fscanf(
     public function fwrite(
         #[LanguageLevelTypeAware(['8.0' => 'string'], default: '')] $data,
         #[LanguageLevelTypeAware(['8.0' => 'int', '8.5' => 'int|null'], default: '')] $length = null
-    ): int|false {}
+    ) {}
 
     /**
      * Gets information about the file
@@ -1275,7 +1275,7 @@ public function current(): mixed {}
     /**
      * Return current node index
      * @link https://php.net/manual/en/spldoublylinkedlist.key.php
-     * @return string|float|int|bool|null The current node index.
+     * @return int The current node index.
      */
     #[TentativeType]
     public function key(): int {}

curl/curl.php

@@ -2618,7 +2618,7 @@ function curl_close(#[LanguageLevelTypeAware(['8.0' => 'CurlHandle'], default: '
  * @return resource|CurlMultiHandle a cURL multi handle resource or object depends on the php version
  */
 #[LanguageLevelTypeAware(['8.0' => 'CurlMultiHandle'], default: 'resource')]
-function curl_multi_init(): CurlMultiHandle {}
+function curl_multi_init() {}
 
 /**
  * Add a normal cURL handle to a cURL multi handle

date/date_c.php

@@ -119,8 +119,8 @@ public function diff(
      * Format accepted by  {@link https://php.net/manual/en/function.date.php date()}.
      * </p>
      * @return string
-     * Returns the formatted date string on success or <b>FALSE</b> on failure.
-     * Since PHP8, it always returns <b>STRING</b>.
+     * Returns the formatted date string on success.
+     * Prior to PHP 8.1, <b>FALSE</b> was returned on failure.
      */
     #[Pure(true)]
     #[TentativeType]
@@ -131,12 +131,12 @@ public function format(#[LanguageLevelTypeAware(['8.0' => 'string'], default: ''
      * Returns the timezone offset
      * @link https://php.net/manual/en/datetime.getoffset.php
      * @return int|false
-     * Returns the timezone offset in seconds from UTC on success
-     * or <b>FALSE</b> on failure. Since PHP8, it always returns <b>INT</b>.
+     * Returns the timezone offset in seconds from UTC on success.
+     * Prior to PHP 8.0, <b>FALSE</b> was returned on failure.
      */
     #[LanguageLevelTypeAware(["8.0" => "int"], default: "int|false")]
     #[TentativeType]
-    public function getOffset(): int;
+    public function getOffset();
 
     /**
      * (PHP 5 &gt;=5.5.0)<br/>
@@ -448,8 +448,9 @@ public static function __set_state(array $array): static {}
      * @param int $year <p>Year of the date.</p>
      * @param int $month <p>Month of the date.</p>
      * @param int $day <p>Day of the date.</p>
-     * @return static|false
-     * Returns the {@link https://php.net/manual/en/class.datetimeimmutable.php DateTimeImmutable} object for method chaining or <b>FALSE</b> on failure.
+     * @return static
+     * Returns the {@link https://php.net/manual/en/class.datetimeimmutable.php DateTimeImmutable} object for method chaining.
+     * Prior to PHP 8.1, <b>FALSE</b> was returned on failure.
      */
     #[TentativeType]
     #[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
@@ -466,8 +467,9 @@ public function setDate(
      * @param int $year <p>Year of the date.</p>
      * @param int $week <p>Week of the date.</p>
      * @param int $dayOfWeek [optional] <p>Offset from the first day of the week.</p>
-     * @return static|false
-     * Returns the {@link https://php.net/manual/en/class.datetimeimmutable.php DateTimeImmutable} object for method chaining or <b>FALSE</b> on failure.
+     * @return static
+     * Returns the {@link https://php.net/manual/en/class.datetimeimmutable.php DateTimeImmutable} object for method chaining.
+     * Prior to PHP 8.1, <b>FALSE</b> was returned on failure.
      */
     #[TentativeType]
     #[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
@@ -485,8 +487,9 @@ public function setISODate(
      * @param int $minute <p> Minute of the time. </p>
      * @param int $second [optional] <p> Second of the time. </p>
      * @param int $microsecond [optional] <p> Microseconds of the time. Added since 7.1</p>
-     * @return static|false
-     * Returns the {@link https://php.net/manual/en/class.datetimeimmutable.php DateTimeImmutable} object for method chaining or <b>FALSE</b> on failure.
+     * @return static
+     * Returns the {@link https://php.net/manual/en/class.datetimeimmutable.php DateTimeImmutable} object for method chaining.
+     * Prior to PHP 8.1, <b>FALSE</b> was returned on failure.
      */
     #[TentativeType]
     #[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
@@ -505,7 +508,7 @@ public function setTime(
      * @param int $timestamp <p>Unix timestamp representing the date.</p>
      * @return static
      * Returns the {@link https://php.net/manual/en/class.datetimeimmutable.php DateTimeImmutable} object for method chaining.
-     * Prior to PHP 8.0, <b>FALSE</b> was returned on failure.
+     * Prior to PHP 8.1, <b>FALSE</b> was returned on failure.
      */
     #[TentativeType]
     #[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
@@ -521,7 +524,7 @@ public function setTimestamp(#[LanguageLevelTypeAware(['8.0' => 'int'], default:
      * </p>
      * @return static
      * Returns the {@link https://php.net/manual/en/class.datetimeimmutable.php DateTimeImmutable} object for method chaining.
-     * Prior to PHP 8.0, <b>FALSE</b> was returned on failure.
+     * Prior to PHP 8.1, <b>FALSE</b> was returned on failure.
      */
     #[TentativeType]
     #[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
@@ -567,7 +570,7 @@ public function diff(
      * </p>
      * @return string
      * Returns the formatted date string on success.
-     * Prior to PHP 8.0, <b>FALSE</b> was returned on failure.
+     * Prior to PHP 8.1, <b>FALSE</b> was returned on failure.
      */
     #[Pure(true)]
     #[TentativeType]
@@ -579,7 +582,7 @@ public function format(#[LanguageLevelTypeAware(['8.0' => 'string'], default: ''
      * @link https://php.net/manual/en/datetime.getoffset.php
      * @return int
      * Returns the timezone offset in seconds from UTC on success.
-     * Prior to PHP 8.0, <b>FALSE</b> was returned on failure.
+     * Prior to PHP 8.1, <b>FALSE</b> was returned on failure.
      */
     #[TentativeType]
     public function getOffset(): int {}

dom/dom_c.php

@@ -945,7 +945,8 @@ public function createElement(
     /**
      * Create new document fragment
      * @link https://php.net/manual/en/domdocument.createdocumentfragment.php
-     * @return DOMDocumentFragment|false The new DOMDocumentFragment or false if an error occurred.
+     * @return DOMDocumentFragment The new DOMDocumentFragment.
+     * Prior to PHP 8.1, false was returned if an error occurred.
      */
     #[TentativeType]
     public function createDocumentFragment(): DOMDocumentFragment {}
@@ -956,7 +957,8 @@ public function createDocumentFragment(): DOMDocumentFragment {}
      * @param string $data <p>
      * The content of the text.
      * </p>
-     * @return DOMText|false The new DOMText or false if an error occurred.
+     * @return DOMText The new DOMText.
+     * Prior to PHP 8.1, false was returned if an error occurred.
      */
     #[TentativeType]
     public function createTextNode(#[LanguageLevelTypeAware(['8.0' => 'string'], default: '')] $data): DOMText {}
@@ -967,7 +969,8 @@ public function createTextNode(#[LanguageLevelTypeAware(['8.0' => 'string'], def
      * @param string $data <p>
      * The content of the comment.
      * </p>
-     * @return DOMComment|false The new DOMComment or false if an error occurred.
+     * @return DOMComment The new DOMComment.
+     * Prior to PHP 8.1, false was returned if an error occurred.
      */
     #[TentativeType]
     public function createComment(#[LanguageLevelTypeAware(['8.0' => 'string'], default: '')] $data): DOMComment {}

gmp/gmp.php

@@ -51,7 +51,7 @@ function gmp_intval(GMP|string|int $num): int {}
  * @throws \ValueError Throws a ValueError if seed is invalid.
  */
 #[LanguageLevelTypeAware(['8.0' => 'void'], default: 'void|false')]
-function gmp_random_seed(GMP|string|int $seed): void {}
+function gmp_random_seed(GMP|string|int $seed) {}
 /**
  * Convert GMP number to string
  * @link https://php.net/manual/en/function.gmp-strval.php
@@ -682,7 +682,7 @@ function gmp_hamdist(GMP|string|int $num1, GMP|string|int $num2): int {}
  */
 #[Pure]
 #[LanguageLevelTypeAware(['8.0' => 'GMP'], default: 'GMP|false')]
-function gmp_import(string $data, int $word_size = 1, int $flags = GMP_MSW_FIRST|GMP_NATIVE_ENDIAN): GMP {}
+function gmp_import(string $data, int $word_size = 1, int $flags = GMP_MSW_FIRST|GMP_NATIVE_ENDIAN) {}
 
 /**
  * Export to a binary string
@@ -696,7 +696,7 @@ function gmp_import(string $data, int $word_size = 1, int $flags = GMP_MSW_FIRST
  */
 #[Pure]
 #[LanguageLevelTypeAware(['8.0' => 'string'], default: 'string|false')]
-function gmp_export(GMP|string|int $num, int $word_size = 1, int $flags = GMP_MSW_FIRST|GMP_NATIVE_ENDIAN): string {}
+function gmp_export(GMP|string|int $num, int $word_size = 1, int $flags = GMP_MSW_FIRST|GMP_NATIVE_ENDIAN) {}
 
 /**
  * Takes the nth root of a and returns the integer component of the result.
@@ -750,7 +750,7 @@ function gmp_nextprime(GMP|string|int $num): GMP {}
  */
 #[Pure]
 #[LanguageLevelTypeAware(['8.0' => 'GMP'], default: 'GMP|false')]
-function gmp_binomial(GMP|string|int $n, int $k): GMP {}
+function gmp_binomial(GMP|string|int $n, int $k) {}
 
 /**
  * Computes the Kronecker symbol

mbstring/mbstring.php

@@ -1019,7 +1019,7 @@ function mb_ereg(string $pattern, string $string, &$matches = null): bool {}
  */
 #[LanguageLevelTypeAware(["8.0" => "bool"], default: "false|int")]
 #[Deprecated(since: '8.6')]
-function mb_eregi(string $pattern, string $string, &$matches = null): bool {}
+function mb_eregi(string $pattern, string $string, &$matches = null) {}
 
 /**
  * Replace regular expression with multibyte support