[12.x] Add ucwords to Str and Stringable (laravel#57581)

* feat: add ucwords to Str and Stringable

* refactor: match native ucwords definition

* test: Str::ucwords()

* test: acronym preservation and custom separator for Str::ucwords()

Author: braxey

src/Illuminate/Support/Str.php

@@ -1827,6 +1827,22 @@ public static function ucfirst($string)
         return static::upper(static::substr($string, 0, 1)).static::substr($string, 1);
     }
 
+    /**
+     * Capitalize the first character of each word in a string.
+     *
+     * @param  string  $string
+     * @param  string  $separators
+     * @return string
+     */
+    public static function ucwords($string, $separators = " \t\r\n\f\v")
+    {
+        $pattern = '/(^|['.preg_quote($separators, '/').'])(\p{Ll})/u';
+
+        return preg_replace_callback($pattern, function ($matches) {
+            return $matches[1].mb_strtoupper($matches[2]);
+        }, $string);
+    }
+
     /**
      * Split a string into pieces by uppercase characters.
      *

src/Illuminate/Support/Stringable.php

@@ -1107,6 +1107,16 @@ public function ucfirst()
         return new static(Str::ucfirst($this->value));
     }
 
+    /**
+     * Capitalize the first character of each word in a string.
+     *
+     * @return static
+     */
+    public function ucwords()
+    {
+        return new static(Str::ucwords($this->value));
+    }
+
     /**
      * Split a string by uppercase characters.
      *

tests/Support/SupportStrTest.php

@@ -1291,6 +1291,16 @@ public function testUcfirst()
         $this->assertSame('Мама мыла раму', Str::ucfirst('мама мыла раму'));
     }
 
+    public function testUcwords()
+    {
+        $this->assertSame('Laravel', Str::ucwords('laravel'));
+        $this->assertSame('Laravel Framework', Str::ucwords('laravel framework'));
+        $this->assertSame('Laravel-Framework', Str::ucwords('laravel-framework', '-'));
+        $this->assertSame('Мама', Str::ucwords('мама'));
+        $this->assertSame('Мама Мыла Раму', Str::ucwords('мама мыла раму'));
+        $this->assertSame('JJ Watt', Str::ucwords('JJ watt'));
+    }
+
     public function testUcsplit()
     {
         $this->assertSame(['Laravel_p_h_p_framework'], Str::ucsplit('Laravel_p_h_p_framework'));