feat(str): add replaceLast() method

Author: oniice

docs/methods.md

@@ -685,6 +685,19 @@ echo $str->replaceFirst('xyz', 'baz');
 // foo bar foo
 ```
 
+### replaceLast `Utility`
+Replace the last occurrence of a value in the string
+
+```php
+$str = new Utility('foo bar foo')
+
+echo $str->replaceLast('foo', 'baz');
+// foo bar baz
+
+echo $str->replaceLast('xyz', 'baz');
+// foo bar foo
+```
+
 ### reverse `Utility`
 Reverse the string
 

src/Utility.php

@@ -714,6 +714,27 @@ public function replaceFirst(string $search, string $replace): Utility
         return static::make($before . $replace . $after, $this->encoding);
     }
 
+    /**
+     * Replace the last occurrence of a value in the string
+     */
+    public function replaceLast(string $search, string $replace): Utility
+    {
+        if ($search === '') {
+            return static::make($this->string, $this->encoding);
+        }
+
+        $position = mb_strrpos($this->string, $search, 0, $this->encoding);
+
+        if ($position === false) {
+            return static::make($this->string, $this->encoding);
+        }
+
+        $before = mb_substr($this->string, 0, $position, $this->encoding);
+        $after = mb_substr($this->string, $position + mb_strlen($search, $this->encoding), null, $this->encoding);
+
+        return static::make($before . $replace . $after, $this->encoding);
+    }
+
     /**
      * Replace none alpha characters in the string with the given value
      */

tests/ReplaceLastTest.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use Iterator;
+
+final class ReplaceLastTest extends BaseStringSuite
+{
+    public static function __validData(): Iterator
+    {
+        yield ['foo bar baz', 'foo bar foo', 'foo', 'baz'];
+        yield ['Hello World', 'Hello World', 'xyz', 'abc'];
+        yield ['Hello World', 'Hello World', '', 'abc'];
+        yield ['Hello  World', 'Hello Hello World', 'Hello', ''];
+        yield ['', '', 'foo', 'bar'];
+        yield ['foobär', 'foobaz', 'baz', 'bär'];
+        yield ['foo-bar-baz', 'foo-bar-bar', 'bar', 'baz'];
+        yield ['fooXX', 'foobar', 'bar', 'XX'];
+        yield ['foobar', 'foobar', 'BAR', 'XX'];
+        yield ['a::b::X', 'a::b::c', 'c', 'X'];
+        yield ['foo.bar.XX', 'foo.bar.baz', 'baz', 'XX'];
+    }
+
+    #[DataProvider('__validData')]
+    public function testReplaceLastMethod(string $expected, string $string, string $search, string $replace): void
+    {
+        $this->assertSame($expected, $this->utility($string)->replaceLast($search, $replace)->value());
+    }
+}