feature #435 [PHP 8.3] Polyfill mb_str_pad() (IonBazan)

This PR was squashed before being merged into the 1.28-dev branch.

Discussion
----------

[PHP 8.3] Polyfill mb_str_pad()

Polyfills the `mb_str_pad()` function added in PHP 8.3: https://wiki.php.net/rfc/mb_str_pad

Test cases were taken from the RFC implementation and adapted to PHPUnit.

Commits
-------

7ccd416 [PHP 8.3] Polyfill mb_str_pad()

Author: nicolas-grekas

Mbstring.php

@@ -827,6 +827,50 @@ public static function mb_ord($s, $encoding = null)
         return $code;
     }
 
+    public static function mb_str_pad(string $string, int $length, string $pad_string = ' ', int $pad_type = \STR_PAD_RIGHT, string $encoding = null): string
+    {
+        if (!\in_array($pad_type, [\STR_PAD_RIGHT, \STR_PAD_LEFT, \STR_PAD_BOTH], true)) {
+            throw new \ValueError('mb_str_pad(): Argument #4 ($pad_type) must be STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH');
+        }
+
+        if (null === $encoding) {
+            $encoding = self::mb_internal_encoding();
+        }
+
+        try {
+            $validEncoding = @self::mb_check_encoding('', $encoding);
+        } catch (\ValueError $e) {
+            throw new \ValueError(sprintf('mb_str_pad(): Argument #5 ($encoding) must be a valid encoding, "%s" given', $encoding));
+        }
+
+        // BC for PHP 7.3 and lower
+        if (!$validEncoding) {
+            throw new \ValueError(sprintf('mb_str_pad(): Argument #5 ($encoding) must be a valid encoding, "%s" given', $encoding));
+        }
+
+        if (self::mb_strlen($pad_string, $encoding) <= 0) {
+            throw new \ValueError('mb_str_pad(): Argument #3 ($pad_string) must be a non-empty string');
+        }
+
+        $paddingRequired = $length - self::mb_strlen($string, $encoding);
+
+        if ($paddingRequired < 1) {
+            return $string;
+        }
+
+        switch ($pad_type) {
+            case \STR_PAD_LEFT:
+                return self::mb_substr(str_repeat($pad_string, $paddingRequired), 0, $paddingRequired, $encoding).$string;
+            case \STR_PAD_RIGHT:
+                return $string.self::mb_substr(str_repeat($pad_string, $paddingRequired), 0, $paddingRequired, $encoding);
+            default:
+                $leftPaddingLength = floor($paddingRequired / 2);
+                $rightPaddingLength = $paddingRequired - $leftPaddingLength;
+
+                return self::mb_substr(str_repeat($pad_string, $leftPaddingLength), 0, $leftPaddingLength, $encoding).$string.self::mb_substr(str_repeat($pad_string, $rightPaddingLength), 0, $rightPaddingLength, $encoding);
+        }
+    }
+
     private static function getSubpart($pos, $part, $haystack, $encoding)
     {
         if (false === $pos) {

bootstrap.php

@@ -132,6 +132,10 @@ function mb_scrub($string, $encoding = null) { $encoding = null === $encoding ?
     function mb_str_split($string, $length = 1, $encoding = null) { return p\Mbstring::mb_str_split($string, $length, $encoding); }
 }
 
+if (!function_exists('mb_str_pad')) {
+    function mb_str_pad(string $string, int $length, string $pad_string = ' ', int $pad_type = STR_PAD_RIGHT, ?string $encoding = null): string { return p\Mbstring::mb_str_pad($string, $length, $pad_string, $pad_type, $encoding); }
+}
+
 if (extension_loaded('mbstring')) {
     return;
 }

bootstrap80.php

@@ -128,6 +128,10 @@ function mb_scrub(?string $string, ?string $encoding = null): string { $encoding
     function mb_str_split(?string $string, ?int $length = 1, ?string $encoding = null): array { return p\Mbstring::mb_str_split((string) $string, (int) $length, $encoding); }
 }
 
+if (!function_exists('mb_str_pad')) {
+    function mb_str_pad(string $string, int $length, string $pad_string = ' ', int $pad_type = STR_PAD_RIGHT, ?string $encoding = null): string { return p\Mbstring::mb_str_pad($string, $length, $pad_string, $pad_type, $encoding); }
+}
+
 if (extension_loaded('mbstring')) {
     return;
 }