feature #466 [mbstring][PHP 8.4] Add mb_ucfirst and mb_lcfirst to polyfills (Ayesh)

This PR was merged into the 1.x branch.

Discussion
----------

[mbstring][PHP 8.4] Add `mb_ucfirst` and `mb_lcfirst` to polyfills

Adds polyfills for `mb_ucfirst` and `mb_lcfirst` functions based on the polyfill shown in PHP.Watch. It basically takes the first mb character, calls `mb_convert_case` with `MB_CASE_TITLE` or `MB_CASE_LOWER`, and returns with the concat of the remaining string.

The tests are taken from the php-src PR.

 - [RFC](https://wiki.php.net/rfc/mb_ucfirst)
 - [php-src PR: php-src#13161](php/php-src#13161)
 - [PHP.Watch - PHP 8.4: New `mb_ucfirst` and `mb_lcfirst` functions](https://php.watch/versions/8.4/mb_ucfirst-mb_ucfirst)

Commits
-------

5bd65b7 [mbstring][PHP 8.4] Add `mb_ucfirst` and `mb_lcfirst` to polyfills

Author: nicolas-grekas

Mbstring.php

@@ -48,6 +48,8 @@
  * - mb_strstr               - Finds first occurrence of a string within another
  * - mb_strwidth             - Return width of string
  * - mb_substr_count         - Count the number of substring occurrences
+ * - mb_ucfirst              - Make a string's first character uppercase
+ * - mb_lcfirst              - Make a string's first character lowercase
  *
  * Not implemented:
  * - mb_convert_kana         - Convert "kana" one from another ("zen-kaku", "han-kaku" and more)
@@ -871,6 +873,51 @@ public static function mb_str_pad(string $string, int $length, string $pad_strin
         }
     }
 
+    public static function mb_ucfirst(string $string, ?string $encoding = null): string
+    {
+        if (null === $encoding) {
+            $encoding = self::mb_internal_encoding();
+        }
+
+        try {
+            $validEncoding = @self::mb_check_encoding('', $encoding);
+        } catch (\ValueError $e) {
+            throw new \ValueError(sprintf('mb_ucfirst(): Argument #2 ($encoding) must be a valid encoding, "%s" given', $encoding));
+        }
+
+        // BC for PHP 7.3 and lower
+        if (!$validEncoding) {
+            throw new \ValueError(sprintf('mb_ucfirst(): Argument #2 ($encoding) must be a valid encoding, "%s" given', $encoding));
+        }
+
+        $firstChar = mb_substr($string, 0, 1, $encoding);
+        $firstChar = mb_convert_case($firstChar, MB_CASE_TITLE, $encoding);
+
+        return $firstChar . mb_substr($string, 1, null, $encoding);
+    }
+
+    public static function mb_lcfirst(string $string, ?string $encoding = null): string
+    {
+        if (null === $encoding) {
+            $encoding = self::mb_internal_encoding();
+        }
+
+        try {
+            $validEncoding = @self::mb_check_encoding('', $encoding);
+        } catch (\ValueError $e) {
+            throw new \ValueError(sprintf('mb_lcfirst(): Argument #2 ($encoding) must be a valid encoding, "%s" given', $encoding));
+        }
+
+        // BC for PHP 7.3 and lower
+        if (!$validEncoding) {
+            throw new \ValueError(sprintf('mb_lcfirst(): Argument #2 ($encoding) must be a valid encoding, "%s" given', $encoding));
+        }
+        $firstChar = mb_substr($string, 0, 1, $encoding);
+        $firstChar = mb_convert_case($firstChar, MB_CASE_LOWER, $encoding);
+
+        return $firstChar . mb_substr($string, 1, null, $encoding);
+    }
+
     private static function getSubpart($pos, $part, $haystack, $encoding)
     {
         if (false === $pos) {

bootstrap.php

@@ -136,6 +136,14 @@ function mb_str_split($string, $length = 1, $encoding = null) { return p\Mbstrin
     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 (!function_exists('mb_ucfirst')) {
+    function mb_ucfirst(string $string, ?string $encoding = null): string { return p\Mbstring::mb_ucfirst($string, $encoding); }
+}
+
+if (!function_exists('mb_lcfirst')) {
+    function mb_lcfirst(string $string, ?string $encoding = null): string { return p\Mbstring::mb_lcfirst($string, $encoding); }
+}
+
 if (extension_loaded('mbstring')) {
     return;
 }

bootstrap80.php

@@ -132,6 +132,14 @@ function mb_str_split(?string $string, ?int $length = 1, ?string $encoding = nul
     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 (!function_exists('mb_ucfirst')) {
+    function mb_ucfirst($string, ?string $encoding = null): string { return p\Mbstring::mb_ucfirst($string, $encoding); }
+}
+
+if (!function_exists('mb_lcfirst')) {
+    function mb_lcfirst($string, ?string $encoding = null): string { return p\Mbstring::mb_lcfirst($string, $encoding); }
+}
+
 if (extension_loaded('mbstring')) {
     return;
 }