[8.x] Add Str::substrReplace() and `Str::of($string)->substrReplace…

…()` methods for the PHP native `substr_replace()` function (#39988)

* Add substr_replace Str / Stringable helpers

* Return a Stringable instead of a raw string

* Add tests

* Remove unused namespace

* Follow the advice of Style CI by adding a dot at the end of a docblock sentence

* Fix inconsistencies between PHP 7.3/7.4 and 8.0+

* Style

src/Illuminate/Support/Str.php

@@ -875,6 +875,24 @@ public static function substrCount($haystack, $needle, $offset = 0, $length = nu
         }
     }
 
+    /**
+     * Replace text within a portion of a string.
+     *
+     * @param  string|array  $string
+     * @param  string|array  $replace
+     * @param  array|int  $offset
+     * @param  array|int|null  $length
+     * @return string|array
+     */
+    public static function substrReplace($string, $replace, $offset = 0, $length = null)
+    {
+        if ($length === null) {
+            $length = strlen($string);
+        }
+
+        return substr_replace($string, $replace, $offset, $length);
+    }
+
     /**
      * Make a string's first character uppercase.
      *

src/Illuminate/Support/Stringable.php

@@ -709,6 +709,19 @@ public function substrCount($needle, $offset = null, $length = null)
         return Str::substrCount($this->value, $needle, $offset ?? 0, $length);
     }
 
+    /**
+     * Replace text within a portion of a string.
+     *
+     * @param  string|array  $replace
+     * @param  array|int  $offset
+     * @param  array|int|null  $length
+     * @return string|array
+     */
+    public function substrReplace($replace, $offset = 0, $length = null)
+    {
+        return new static(Str::substrReplace($this->value, $replace, $offset, $length));
+    }
+
     /**
      * Trim the string of the given characters.
      *

tests/Support/SupportStrTest.php

@@ -535,6 +535,13 @@ public function testSubstrCount()
         $this->assertSame(1, Str::substrCount('laravelPHPFramework', 'a', -10, -3));
     }
 
+    public function testSubstrReplace()
+    {
+        $this->assertSame('12:00', Str::substrReplace('1200', ':', 2, 0));
+        $this->assertSame('The Laravel Framework', Str::substrReplace('The Framework', 'Laravel ', 4, 0));
+        $this->assertSame('Laravel – The PHP Framework for Web Artisans', Str::substrReplace('Laravel Framework', '– The PHP Framework for Web Artisans', 8));
+    }
+
     public function testUcfirst()
     {
         $this->assertSame('Laravel', Str::ucfirst('laravel'));

tests/Support/SupportStringableTest.php

@@ -621,6 +621,13 @@ public function testSubstrCount()
         $this->assertSame(1, $this->stringable('laravelPHPFramework')->substrCount('a', -10, -3));
     }
 
+    public function testSubstrReplace()
+    {
+        $this->assertSame('12:00', (string) $this->stringable('1200')->substrReplace(':', 2, 0));
+        $this->assertSame('The Laravel Framework', (string) $this->stringable('The Framework')->substrReplace('Laravel ', 4, 0));
+        $this->assertSame('Laravel – The PHP Framework for Web Artisans', (string) $this->stringable('Laravel Framework')->substrReplace('– The PHP Framework for Web Artisans', 8));
+    }
+
     public function testPadBoth()
     {
         $this->assertSame('__Alien___', (string) $this->stringable('Alien')->padBoth(10, '_'));