From 0f501d548dcdb879e1ba07050921b9223dcdd6d4 Mon Sep 17 00:00:00 2001
From: Colin Viebrock <colin@viebrock.ca>
Date: Wed, 25 Sep 2024 14:30:55 -0500
Subject: [PATCH] Add more info on enabling rulesets for foreign languages

---
 .gitignore                               |  1 +
 README.md                                | 30 ++++++++++++++++++++++++
 tests/BaseTests.php                      | 12 ++++++++++
 tests/Models/PostWithForeignRuleset2.php | 29 +++++++++++++++++++++++
 4 files changed, 72 insertions(+)
 create mode 100644 tests/Models/PostWithForeignRuleset2.php

diff --git a/.gitignore b/.gitignore
index 1783d56..cfca156 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 /.php_cs.cache
 /.phpunit.cache
 /.phpunit.result.cache
+/.idea/
 /build/
 /vendor/
 composer.lock
diff --git a/README.md b/README.md
index fd6a1d2..53f3ea7 100644
--- a/README.md
+++ b/README.md
@@ -596,6 +596,36 @@ for Slugify for what those options are.  Also, look at
 [customizeSlugEngine](#customizeslugengine) for other ways to customize Slugify
 for slugging.
 
+A common use for this is to turn on a different ruleset for a specific language.
+For example the string `Jyväskylä` will slug to `jyvaeskylae` using the default settings.
+In Finnish, it really should slug to `jyvaskyla`, so for that to work, you need to enable 
+the Finnish ruleset for the attribute you are slugging:
+
+```php
+public function sluggable(): array
+{
+    return [
+        'slug' => [
+            'source' => 'title',
+            'slugEngineOptions' => [
+                'ruleset' => 'finnish'
+            ]
+        ]
+    ];
+}
+```
+
+This can also be accomplished with the [customizeSlugEngine](#customizeslugengine) method
+(which, unless you add custom logic, will apply to _all_ attributes on the model):
+
+```php
+public function customizeSlugEngine(Slugify $engine, string $attribute): \Cocur\Slugify\Slugify
+{
+    $engine->activateRuleSet('finnish');
+
+    return $engine;
+}
+```
 
 ## Short Configuration
 
diff --git a/tests/BaseTests.php b/tests/BaseTests.php
index d73c5eb..287250f 100644
--- a/tests/BaseTests.php
+++ b/tests/BaseTests.php
@@ -12,6 +12,7 @@
 use Cviebrock\EloquentSluggable\Tests\Models\PostWithCustomMethodArrayCall;
 use Cviebrock\EloquentSluggable\Tests\Models\PostWithCustomSeparator;
 use Cviebrock\EloquentSluggable\Tests\Models\PostWithCustomSource;
+use Cviebrock\EloquentSluggable\Tests\Models\PostWithForeignRuleset2;
 use Cviebrock\EloquentSluggable\Tests\Models\PostWithIdSource;
 use Cviebrock\EloquentSluggable\Tests\Models\PostWithCustomSuffix;
 use Cviebrock\EloquentSluggable\Tests\Models\PostWithEmptySeparator;
@@ -428,6 +429,17 @@ public function testForeignRuleset(): void
         self::assertEquals('mia-unua-posxto', $post->slug);
     }
 
+    /**
+     * Test using a custom Slugify ruleset.
+     */
+    public function testForeignRuleset2(): void
+    {
+        $post = PostWithForeignRuleset2::create([
+            'title' => 'Jyväskylä'
+        ]);
+        self::assertEquals('jyvaskyla', $post->slug);
+    }
+
     /**
      * Test if using an empty separator works.
      *
diff --git a/tests/Models/PostWithForeignRuleset2.php b/tests/Models/PostWithForeignRuleset2.php
new file mode 100644
index 0000000..b5d459c
--- /dev/null
+++ b/tests/Models/PostWithForeignRuleset2.php
@@ -0,0 +1,29 @@
+<?php namespace Cviebrock\EloquentSluggable\Tests\Models;
+
+/**
+ * Class PostWithForeignRuleset
+ *
+ * A test model that customizes the Slugify engine with a foreign ruleset.
+ *
+ * @package Cviebrock\EloquentSluggable\Tests\Models
+ */
+class PostWithForeignRuleset2 extends Post
+{
+
+    /**
+     * Return the sluggable configuration array for this model.
+     *
+     * @return array
+     */
+    public function sluggable(): array
+    {
+        return [
+            'slug' => [
+                'source' => 'title',
+                'slugEngineOptions' => [
+                    'ruleset' => 'finnish'
+                ],
+            ],
+        ];
+    }
+}