feat(support): add words and sentence methods to string utils (#1042)

Author: innocenzi

src/Tempest/Support/src/Str/ManipulatesString.php

@@ -187,6 +187,22 @@ public function slug(Stringable|string $separator = '-', array $replacements = [
         return $this->createOrModify(to_slug($this->value, $separator, $replacements, $replaceSymbols));
     }
 
+    /**
+     * Converts the current string to a naive sentence case.
+     */
+    public function sentence(): static
+    {
+        return $this->createOrModify(to_sentence_case($this->value));
+    }
+
+    /**
+     * Returns an array of words from the current string.
+     */
+    public function words(): ImmutableArray
+    {
+        return new ImmutableArray(to_words($this->value));
+    }
+
     /**
      * Transliterates the current string to ASCII. Invalid characters are replaced with their closest counterpart.
      *

src/Tempest/Support/src/Str/functions.php

@@ -6,6 +6,7 @@
     use ArrayAccess;
     use Countable;
     use Stringable;
+    use Tempest\Support\Arr\ImmutableArray;
     use Tempest\Support\Language;
     use voku\helper\ASCII;
 
@@ -22,6 +23,19 @@ function to_title_case(Stringable|string $string): string
         return mb_convert_case((string) $string, mode: MB_CASE_TITLE, encoding: 'UTF-8');
     }
 
+    /**
+     * Converts the given string to a naive sentence case. This doesn't detect proper nouns and proper adjectives that should stay capitalized.
+     */
+    function to_sentence_case(Stringable|string $string): string
+    {
+        $words = array_map(
+            callback: fn (string $string) => to_lower_case($string),
+            array: to_words($string),
+        );
+
+        return upper_first(implode(' ', $words));
+    }
+
     /**
      * Converts the given string to lower case.
      */
@@ -51,17 +65,35 @@ function to_snake_case(Stringable|string $string, Stringable|string $delimiter =
         }
 
         $string = preg_replace('/(.)(?=[A-Z])/u', '$1' . $delimiter, $string);
-        $string = preg_replace(
-            '![^' . preg_quote($delimiter) . '\pL\pN\s]+!u',
-            $delimiter,
-            mb_strtolower($string, 'UTF-8'),
-        );
+        $string = preg_replace('![^' . preg_quote($delimiter) . '\pL\pN\s]+!u', $delimiter, mb_strtolower($string, 'UTF-8'));
         $string = preg_replace('/\s+/u', $delimiter, $string);
         $string = trim($string, $delimiter);
 
         return deduplicate($string, $delimiter);
     }
 
+    /**
+     * Returns an array of words from the specified string.
+     * This is more accurate than {@see str_word_count()}.
+     */
+    function to_words(Stringable|string $string): array
+    {
+        // Remove 'words' that don't consist of alphanumerical characters or punctuation
+        $words = trim(preg_replace("#[^(\w|\d|\'|\"|\.|\!|\?|;|,|\\|\/|\-|:|\&|@)]+#", ' ', (string) $string));
+        // Remove one-letter 'words' that consist only of punctuation
+        $words = trim(preg_replace("#\s*[(\'|\"|\.|\!|\?|;|,|\\|\/|\-|:|\&|@)]\s*#", ' ', $words));
+
+        return array_values(array_filter(explode(' ', namespace\deduplicate($words))));
+    }
+
+    /**
+     * Counts the number of words in the given string.
+     */
+    function word_count(Stringable|string $string): int
+    {
+        return count(to_words($string));
+    }
+
     /**
      * Converts the given string to kebab case.
      */

src/Tempest/Support/tests/Str/ManipulatesStringTest.php

@@ -700,4 +700,27 @@ public function test_is_ascii(): void
         $this->assertFalse(str('helloü')->isAscii());
         $this->assertFalse(str('بسم الله')->isAscii());
     }
+
+    #[TestWith(['foo bar baz', ['foo', 'bar', 'baz']])]
+    #[TestWith(['foo-bar-baz', ['foo', 'bar', 'baz']])]
+    #[TestWith(['1foo_bar1', ['1foo_bar1']])]
+    #[TestWith(['fooBar', ['fooBar']])]
+    #[TestWith(['Jon Doe', ['Jon', 'Doe']])]
+    #[TestWith(['-Jon Doe', ['Jon', 'Doe']])]
+    #[TestWith(['_Jon_Doe', ['_Jon_Doe']])]
+    public function test_words(string $input, array $output): void
+    {
+        $this->assertEquals($output, str($input)->words()->toArray());
+    }
+
+    #[TestWith(['foo bar baz', 'Foo bar baz'])]
+    #[TestWith(['foo-bar-baz', 'Foo bar baz'])]
+    #[TestWith(['Foo Bar', 'Foo bar'])]
+    #[TestWith(['1foo_bar1', '1foo_bar1'])]
+    #[TestWith(['getting-started', 'Getting started'])]
+    #[TestWith(['Getting Started', 'Getting started'])]
+    public function test_sentence(string $input, string $output): void
+    {
+        $this->assertEquals($output, str($input)->sentence()->toString());
+    }
 }