feat(support): add slug, ascii and isAscii to string utils (#1040)

Author: innocenzi

composer.json

@@ -34,7 +34,8 @@
         "symfony/var-dumper": "^7.1",
         "symfony/var-exporter": "^7.1",
         "tempest/highlight": "^2.11.2",
-        "vlucas/phpdotenv": "^5.6"
+        "vlucas/phpdotenv": "^5.6",
+        "voku/portable-ascii": "^2.0.3"
     },
     "require-dev": {
         "aidan-casey/mock-client": "dev-master",

src/Tempest/Support/composer.json

@@ -7,7 +7,8 @@
         "php": "^8.4",
         "doctrine/inflector": "^2.0",
         "tempest/container": "dev-main",
-        "tempest/highlight": "^2.11.2"
+        "tempest/highlight": "^2.11.2",
+        "voku/portable-ascii": "^2.0.3"
     },
     "autoload": {
         "psr-4": {

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

@@ -177,6 +177,34 @@ public function camel(): static
         return $this->createOrModify(to_camel_case($this->value));
     }
 
+    /**
+     * Converts the current string to an URL-safe slug.
+     *
+     * @param bool $replaceSymbols Adds some more replacements e.g. "£" with "pound".
+     */
+    public function slug(Stringable|string $separator = '-', array $replacements = [], bool $replaceSymbols = true): static
+    {
+        return $this->createOrModify(to_slug($this->value, $separator, $replacements, $replaceSymbols));
+    }
+
+    /**
+     * Transliterates the current string to ASCII. Invalid characters are replaced with their closest counterpart.
+     *
+     * @param string $language Language of the source string. Defaults to english.
+     */
+    public function ascii(Stringable|string $language = 'en'): static
+    {
+        return $this->createOrModify(to_ascii($this->value, $language));
+    }
+
+    /**
+     * Asserts whether the instance is an ASCII string.
+     */
+    public function isAscii(): bool
+    {
+        return is_ascii($this->value);
+    }
+
     /**
      * Replaces consecutive instances of a given character with a single character.
      */

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

@@ -7,6 +7,7 @@
     use Countable;
     use Stringable;
     use Tempest\Support\Language;
+    use voku\helper\ASCII;
 
     use function levenshtein as php_levenshtein;
     use function metaphone as php_metaphone;
@@ -89,6 +90,34 @@ function to_camel_case(Stringable|string $string): string
         return lcfirst(to_pascal_case((string) $string));
     }
 
+    /**
+     * Converts the given string to an URL-safe slug.
+     *
+     * @param bool $replaceSymbols Adds some more replacements e.g. "£" with "pound".
+     */
+    function to_slug(Stringable|string $string, Stringable|string $separator = '-', array $replacements = [], bool $replaceSymbols = true): string
+    {
+        return ASCII::to_slugify((string) $string, (string) $separator, replacements: $replacements, replace_extra_symbols: $replaceSymbols);
+    }
+
+    /**
+     * Transliterates the given string to ASCII.
+     *
+     * @param string $language Language of the source string. Defaults to english.
+     */
+    function to_ascii(Stringable|string $string, Stringable|string $language = 'en'): string
+    {
+        return ASCII::to_ascii((string) $string, (string) $language, replace_single_chars_only: false);
+    }
+
+    /**
+     * Checks whether the given string is valid ASCII.
+     */
+    function is_ascii(Stringable|string $string): bool
+    {
+        return ASCII::is_ascii((string) $string);
+    }
+
     /**
      * Converts the given string to its English plural form.
      */

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

@@ -663,4 +663,41 @@ public function test_basename(): void
         $this->assertSame('file', str('file.txt')->basename('.txt')->toString());
         $this->assertSame('', str()->basename()->toString());
     }
+
+    public function test_ascii(): void
+    {
+        $this->assertSame('@', str('@')->ascii()->toString());
+        $this->assertSame('u', str('ü')->ascii()->toString());
+        $this->assertSame('', str('')->ascii()->toString());
+        $this->assertSame('a!2e', str('a!2ë')->ascii()->toString());
+    }
+
+    public function test_slug(): void
+    {
+        $this->assertSame('hello-world', str('hello world')->slug()->toString());
+        $this->assertSame('hello-world', str('hello-world')->slug()->toString());
+        $this->assertSame('hello-world', str('hello_world')->slug()->toString());
+        $this->assertSame('hello_world', str('hello_world')->slug(separator: '_')->toString());
+        $this->assertSame('user-at-host', str('user@host')->slug()->toString());
+        $this->assertSame('slam-dnya', str('سلام دنیا')->slug(separator: '-')->toString());
+        $this->assertSame('sometext', str('some text')->slug(separator: '')->toString());
+        $this->assertSame('', str()->slug(separator: '')->toString());
+        $this->assertSame('bsm-allh', str('بسم الله')->slug(separator: '-', replacements: ['allh' => 'allah'])->toString());
+        $this->assertSame('500-dollar-bill', str('500$ bill')->slug('-', replaceSymbols: true)->toString());
+        $this->assertSame('500-bill', str('500$ bill')->slug('-', replaceSymbols: false)->toString());
+        $this->assertSame('500-dollar-bill', str('500--$----bill')->slug(separator: '-')->toString());
+        $this->assertSame('500-dollar-bill', str('500-$-bill')->slug(separator: '-')->toString());
+        $this->assertSame('500-dollar-bill', str('500$--bill')->slug(separator: '-')->toString());
+        $this->assertSame('500-dollar-bill', str('500-$--bill')->slug(separator: '-')->toString());
+        $this->assertSame('ahmdfyalmdrs', str('أحمد@المدرسة')->slug(separator: '-', replacements: ['@' => 'في'])->toString());
+    }
+
+    public function test_is_ascii(): void
+    {
+        $this->assertTrue(str('hello')->isAscii());
+        $this->assertTrue(str()->isAscii());
+
+        $this->assertFalse(str('helloü')->isAscii());
+        $this->assertFalse(str('بسم الله')->isAscii());
+    }
 }