Improve return type of Str::replace() (#57820)

Author: axlon

src/Illuminate/Support/Str.php

@@ -1228,7 +1228,7 @@ private static function toStringOr($value, $fallback)
      * @param  string|iterable<string>  $replace
      * @param  string|iterable<string>  $subject
      * @param  bool  $caseSensitive
-     * @return string|string[]
+     * @return ($subject is string ? string : string[])
      */
     public static function replace($search, $replace, $subject, $caseSensitive = true)
     {

types/Support/Str.php

@@ -33,3 +33,11 @@
 } else {
     assertType('mixed', $uuid);
 }
+
+/**
+ * @var string $search
+ * @var string $replace
+ * @var string $subject
+ */
+assertType('string', Str::replace($search, $replace, $subject));
+assertType('array<string>', Str::replace($search, $replace, [$subject]));