Added regexReplace()

README.md

@@ -38,6 +38,7 @@ A PHP library with a variety of string manipulation functions with multibyte sup
     * [padBoth](#padboth)
     * [padLeft](#padleft)
     * [padRight](#padright)
+    * [regexReplace](#regexreplace)
     * [removeLeft](#removeleft)
     * [removeRight](#removeright)
     * [replace](#replace)
@@ -548,6 +549,22 @@ S::create('foo bar')->padRight(10, '_*');
 S::padRight('foo bar', 10, '_*');  // 'foo bar_*_'
 ```
 
+#### regexReplace
+
+$stringy->regexReplace(string $pattern, string $replacement [, string $options = 'msr'])
+
+S::regexReplace(string $str, string $pattern, string $replacement [, string $options = 'msr' [, string $encoding ]])
+
+Replaces all occurrences of $pattern in $str by $replacement. An alias
+for mb_ereg_replace(). Note that the 'i' option with multibyte patterns
+in mb_ereg_replace() requires PHP 5.4+. This is due to a lack of support
+in the bundled version of Oniguruma in PHP 5.3.
+
+```php
+S::create('fòô ', UTF-8')->regexReplace('f[òô]+\s', 'bàř', 'msr');
+S::regexReplace('fòô ', 'f[òô]+\s', 'bàř', 'msr', 'UTF-8');  // 'bàř'
+```
+
 #### removeLeft
 
 $stringy->removeLeft(string $substring)

src/Stringy/StaticStringy.php

@@ -744,4 +744,24 @@ class StaticStringy
     {
         return Stringy::create($str, $encoding)->replace($search, $replace)->str;
     }
+
+    /**
+     * Replaces all occurrences of $pattern in $str by $replacement. An alias
+     * for mb_ereg_replace(). Note that the 'i' option with multibyte patterns
+     * in mb_ereg_replace() requires PHP 5.4+. This is due to a lack of support
+     * in the bundled version of Oniguruma in PHP 5.3.
+     *
+     * @param   string   $str          The haystack to search through
+     * @param   string   $pattern      The regular expression pattern
+     * @param   string   $replacement  The string to replace with
+     * @param   string   $options      Matching conditions to be used
+     * @param   string   $encoding     The character encoding
+     * @return  string   The resulting string after the replacements
+     */
+    public static function regexReplace($str, $pattern, $replacement,
+                                        $options = 'msr', $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->regexReplace($pattern,
+            $replacement, $options, $encoding)->str;
+    }
 }

src/Stringy/Stringy.php

@@ -1146,4 +1146,26 @@ class Stringy
 
         return $stringy;
     }
+
+    /**
+     * Replaces all occurrences of $pattern in $str by $replacement. An alias
+     * for mb_ereg_replace(). Note that the 'i' option with multibyte patterns
+     * in mb_ereg_replace() requires PHP 5.4+. This is due to a lack of support
+     * in the bundled version of Oniguruma in PHP 5.3.
+     *
+     * @param   string   $pattern      The regular expression pattern
+     * @param   string   $replacement  The string to replace with
+     * @param   string   $options      Matching conditions to be used
+     * @return  Stringy  Object with the resulting $str after the replacements
+     */
+    public function regexReplace($pattern, $replacement, $options = 'msr')
+    {
+        $regexEncoding = mb_regex_encoding();
+        mb_regex_encoding($this->encoding);
+
+        $str = mb_ereg_replace($pattern, $replacement, $this->str, $options);
+        mb_regex_encoding($regexEncoding);
+
+        return self::create($str, $this->encoding);
+    }
 }

tests/Stringy/CommonTest.php

@@ -939,4 +939,19 @@ abstract class CommonTest extends PHPUnit_Framework_TestCase
 
         return $testData;
     }
+
+    public function stringsForRegexReplace()
+    {
+        $testData = array(
+            array('', '', '', ''),
+            array('bar', 'foo', 'f[o]+', 'bar'),
+            array('bar', 'foo bar', 'f[O]+\s', '', 'i'),
+            array('foo', 'bar', '[[:alpha:]]{3}', 'foo'),
+            array('', '', '', '', 'msr', 'UTF-8'),
+            array('bàř', 'fòô ', 'f[òô]+\s', 'bàř', 'msr', 'UTF-8'),
+            array('fòô', 'bàř', '[[:alpha:]]{3}', 'fòô', 'msr', 'UTF-8')
+        );
+
+        return $testData;
+    }
 }

tests/Stringy/StaticStringyTest.php

@@ -572,4 +572,15 @@ class StaticStringyTestCase extends CommonTest
         $this->assertInternalType('string', $result);
         $this->assertEquals($expected, $result);
     }
+
+    /**
+     * @dataProvider stringsForRegexReplace
+     */
+    public function testRegexReplace($expected, $str, $pattern, $replacement,
+                                     $options = 'msr', $encoding = null)
+    {
+        $result = S::regexReplace($str, $pattern, $replacement, $options, $encoding);
+        $this->assertInternalType('string', $result);
+        $this->assertEquals($expected, $result);
+    }
 }

tests/Stringy/StringyTest.php

@@ -675,4 +675,17 @@ class StringyTestCase extends CommonTest
         $this->assertEquals($expected, $result);
         $this->assertEquals($str, $stringy);
     }
+
+    /**
+     * @dataProvider stringsForRegexReplace
+     */
+    public function testregexReplace($expected, $str, $pattern, $replacement,
+                                     $options = 'msr', $encoding = null)
+    {
+        $stringy = S::create($str, $encoding);
+        $result = $stringy->regexReplace($pattern, $replacement, $options);
+        $this->assertInstanceOf('Stringy\Stringy', $result);
+        $this->assertEquals($expected, $result);
+        $this->assertEquals($str, $stringy);
+    }
 }