New: Add Carbon.String.replaceOnce

Classes/EelHelper/StringHelper.php

@@ -144,6 +144,29 @@ public function convertCamelCase($string, $separator = '-'): string
         );
     }
 
+    /**
+     * Helper to replace the first occurrence of a string
+     *
+     * @param string $string The string being searched and replaced on
+     * @param string $search he value being searched for
+     * @param string|null $replace The replacement value that replaces found search value
+     * @return string
+     */
+    public function replaceOnce(string $string, string $search, ?string $replace = null): string
+    {
+        $pos = strpos($string, $search);
+        if ($pos === false) {
+            return $string;
+        }
+
+        if (!isset($replace)) {
+            $replace = '';
+        }
+
+        return substr_replace($string, $replace, $pos, strlen($search));
+    }
+
+
     /**
      * Helper to make sure we got a string back
      *

README.md

@@ -539,6 +539,23 @@ Examples:
 
 - `emailAddress` (string) The string to check
 
+### `Carbon.String.replaceOnce(string, search, replace)`
+
+Helper to replace the first occurrence of a string.
+
+Examples:
+
+| Expression                                             | Result        |
+| ------------------------------------------------------ | ------------- |
+| `Carbon.String.replaceOnce('Foo Bar Foo', 'Foo', 'X')` | `'X Bar Foo'` |
+| `Carbon.String.replaceOnce('Foo Bar Foo', 'Foo ')`     | `'Bar Foo'`   |
+
+- `string` (string) The string being searched and replaced on
+- `search` (string) The value being searched for
+- `prefix` (string, optional) The replacement value that replaces found search value
+
+Returns the string with one occurrence replaced
+
 ## Number Helper
 
 ### `Carbon.Number.format(number, decimals, dec_point, thousands_sep)`