[8.x] Adds mask() for masking part of a string (#39393)

* [8.x] Adds `mask()` for masking part of a string.

* Removed multi-byte functions due to no string functions consistency.

* Fixed method for PHP 7.3 and PHP 7.4.

* Refactored helper for multi-byte strings and custom encoding.

* Style fixing.

* Update Str.php

Co-authored-by: Taylor Otwell <[email protected]>

Author: DarkGhostHunter

src/Illuminate/Support/Str.php

@@ -398,6 +398,38 @@ public static function markdown($string, array $options = [])
         return (string) $converter->convertToHtml($string);
     }
 
+    /**
+     * Masks a portion of a string with a repeated character.
+     *
+     * @param  string  $string
+     * @param  string  $character
+     * @param  int  $index
+     * @param  int|null  $length
+     * @param  string  $encoding
+     * @return string
+     */
+    public static function mask($string, $character, $index, $length = null, $encoding = 'UTF-8')
+    {
+        if ($character === '') {
+            return $string;
+        }
+
+        if (is_null($length) && PHP_MAJOR_VERSION < 8) {
+            $length = mb_strlen($string, $encoding);
+        }
+
+        $segment = mb_substr($string, $index, $length, $encoding);
+
+        if ($segment === '') {
+            return $string;
+        }
+
+        $start = mb_substr($string, 0, mb_strpos($string, $segment, 0, $encoding), $encoding);
+        $end = mb_substr($string, mb_strpos($string, $segment, 0, $encoding) + mb_strlen($segment, $encoding));
+
+        return $start.str_repeat(mb_substr($character, 0, 1, $encoding), mb_strlen($segment, $encoding)).$end;
+    }
+
     /**
      * Get the string matching the given pattern.
      *

src/Illuminate/Support/Stringable.php

@@ -342,6 +342,20 @@ public function markdown(array $options = [])
         return new static(Str::markdown($this->value, $options));
     }
 
+    /**
+     * Masks a portion of a string with a repeated character.
+     *
+     * @param  string  $character
+     * @param  int  $index
+     * @param  int|null  $length
+     * @param  string  $encoding
+     * @return static
+     */
+    public function mask($character, $index, $length = null, $encoding = 'UTF-8')
+    {
+        return new static(Str::mask($this->value, $character, $index, $length, $encoding));
+    }
+
     /**
      * Get the string matching the given pattern.
      *

tests/Support/SupportStrTest.php

@@ -451,6 +451,28 @@ public function testStudly()
         $this->assertSame('FooBarBaz', Str::studly('foo-bar_baz'));
     }
 
+    public function testMask()
+    {
+        $this->assertSame('tay*************', Str::mask('[email protected]', '*', 3));
+        $this->assertSame('******@email.com', Str::mask('[email protected]', '*', 0, 6));
+        $this->assertSame('tay*************', Str::mask('[email protected]', '*', -13));
+        $this->assertSame('tay***@email.com', Str::mask('[email protected]', '*', -13, 3));
+
+        $this->assertSame('****************', Str::mask('[email protected]', '*', -17));
+        $this->assertSame('*****[email protected]', Str::mask('[email protected]', '*', -99, 5));
+
+        $this->assertSame('[email protected]', Str::mask('[email protected]', '*', 16));
+        $this->assertSame('[email protected]', Str::mask('[email protected]', '*', 16, 99));
+
+        $this->assertSame('[email protected]', Str::mask('[email protected]', '', 3));
+
+        $this->assertSame('taysssssssssssss', Str::mask('[email protected]', 'something', 3));
+        $this->assertSame('taysssssssssssss', Str::mask('[email protected]', Str::of('something'), 3));
+
+        $this->assertSame('这是一***', Str::mask('这是一段中文', '*', 3));
+        $this->assertSame('**一段中文', Str::mask('这是一段中文', '*', 0, 2));
+    }
+
     public function testMatch()
     {
         $this->assertSame('bar', Str::match('/bar/', 'foo bar'));

tests/Support/SupportStringableTest.php

@@ -675,6 +675,27 @@ public function testMarkdown()
         $this->assertEquals("<h1>hello world</h1>\n", $this->stringable('# hello world')->markdown());
     }
 
+    public function testMask()
+    {
+        $this->assertEquals('tay*************', $this->stringable('[email protected]')->mask('*', 3));
+        $this->assertEquals('******@email.com', $this->stringable('[email protected]')->mask('*', 0, 6));
+        $this->assertEquals('tay*************', $this->stringable('[email protected]')->mask('*', -13));
+        $this->assertEquals('tay***@email.com', $this->stringable('[email protected]')->mask('*', -13, 3));
+
+        $this->assertEquals('****************', $this->stringable('[email protected]')->mask('*', -17));
+        $this->assertEquals('*****[email protected]', $this->stringable('[email protected]')->mask('*', -99, 5));
+
+        $this->assertEquals('[email protected]', $this->stringable('[email protected]')->mask('*', 16));
+        $this->assertEquals('[email protected]', $this->stringable('[email protected]')->mask('*', 16, 99));
+
+        $this->assertEquals('[email protected]', $this->stringable('[email protected]')->mask('', 3));
+
+        $this->assertEquals('taysssssssssssss', $this->stringable('[email protected]')->mask('something', 3));
+
+        $this->assertEquals('这是一***', $this->stringable('这是一段中文')->mask('*', 3));
+        $this->assertEquals('**一段中文', $this->stringable('这是一段中文')->mask('*', 0, 2));
+    }
+
     public function testRepeat()
     {
         $this->assertSame('aaaaa', (string) $this->stringable('a')->repeat(5));