Merge pull request #289 from josepdecid/customizable-suffix

Allow to generate custom suffixes

Author: freekmurze

README.md

@@ -30,7 +30,8 @@ We highly appreciate you sending us a postcard from your hometown, mentioning wh
 ## Installation
 
 You can install the package via composer:
-``` bash
+
+```bash
 composer require spatie/laravel-sluggable
 ```
 
@@ -281,7 +282,6 @@ public function getSlugOptions() : SlugOptions
 
 ### Using scopes
 
-
 If you have a global scope that should be taken into account, you can define this as well with `extraScope`. For example if you have a pages table containing pages of multiple websites and every website has it's own unique slugs.
 
 ```php
@@ -308,6 +308,40 @@ public function getSlugOptions() : SlugOptions
 }
 ```
 
+### Generating slug suffix on first occurrence
+
+With the default behavior (assuming that we haven't disabled slug uniqueness with `allowDuplicateSlugs`), the generated slugs for two records with the same source values would be `this-is-an-example` and `this-is-an-example-1`.
+
+When using this option, we are forcing the first occurence to also have a suffix so, even if the slug is unique as it is, it will be suffixed, resulting in `this-is-an-example-1` and `this-is-an-example-2`.
+
+```php
+public function getSlugOptions() : SlugOptions
+{
+    return SlugOptions::create()
+        ->generateSlugsFrom('name')
+        ->saveSlugsTo('slug')
+        ->useSuffixOnFirstOccurrence();
+}
+```
+
+### Generating a custom slug suffix
+
+By default, the mechanism to make slugs unique is to append an autoincremental value to the slug. You can generate a custom slug suffix such as a random string or hash with `usingSuffixGenerator`.
+
+It accepts a callable that receives the base slug (without any suffix) and the iteration number, which represents how many times the suffix generation process has been run to ensure uniqueness. This number could be useful to monitor the collision rate of the generation process.
+
+```php
+public function getSlugOptions() : SlugOptions
+{
+    return SlugOptions::create()
+        ->generateSlugsFrom('name')
+        ->saveSlugsTo('slug')
+        ->usingSuffixGenerator(
+            fn(string $slug, int $iteration) => bin2hex(random_bytes(4))
+        ); // Sample dummy method to generate a random hex code of length 8
+}
+```
+
 ### Integration with laravel-translatable
 
 You can use this package along with [laravel-translatable](https://github.com/spatie/laravel-translatable) to generate a slug for each locale. Instead of using the `HasSlug` trait, you must use the `HasTranslatableSlug` trait, and add the name of the slug field to the `$translatable` array. For slugs that are generated from a single field _or_ multiple fields, you don't have to change anything else.
@@ -419,7 +453,6 @@ $model = Article::findBySlug('my-article');
 
 `findBySlug` also accepts a second parameter `$columns` just like the default Eloquent `find` method.
 
-
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

src/HasSlug.php

@@ -128,15 +128,29 @@ protected function getSlugSourceStringFromCallable(): string
     protected function makeSlugUnique(string $slug): string
     {
         $originalSlug = $slug;
-        $i = $this->slugOptions->startSlugSuffixFrom;
+        $iteration = 0;
 
-        while ($this->otherRecordExistsWithSlug($slug) || $slug === '') {
-            $slug = $originalSlug.$this->slugOptions->slugSeparator.$i++;
+        while (
+            $slug === '' ||
+            $this->otherRecordExistsWithSlug($slug) ||
+            ($this->slugOptions->useSuffixOnFirstOccurrence && $iteration === 0)
+        ) {
+            $suffix = $this->generateSuffix($originalSlug, $iteration++);
+            $slug = $originalSlug . $this->slugOptions->slugSeparator . $suffix;
         }
 
         return $slug;
     }
 
+    protected function generateSuffix(string $originalSlug, int $iteration): string
+    {
+        if ($this->slugOptions->suffixGenerator) {
+            return call_user_func($this->slugOptions->suffixGenerator, $originalSlug, $iteration);
+        }
+
+        return strval($this->slugOptions->startSlugSuffixFrom + $iteration);
+    }
+
     protected function otherRecordExistsWithSlug(string $slug): bool
     {
         $query = static::where($this->slugOptions->slugField, $slug)

src/SlugOptions.php

@@ -10,6 +10,9 @@ class SlugOptions
     /** @var callable */
     public $extraScopeCallback;
 
+    /** @var (callable(string $slug, int $iteration): string)|null */
+    public $suffixGenerator;
+
     public string $slugField;
 
     public bool $generateUniqueSlugs = true;
@@ -32,6 +35,8 @@ class SlugOptions
 
     public int $startSlugSuffixFrom = 1;
 
+    public bool $useSuffixOnFirstOccurrence = false;
+
     public static function create(): static
     {
         return new static();
@@ -133,4 +138,22 @@ public function startSlugSuffixFrom(int $startSlugSuffixFrom): self
 
         return $this;
     }
+
+    public function useSuffixOnFirstOccurrence(): self
+    {
+        $this->useSuffixOnFirstOccurrence = true;
+
+        return $this;
+    }
+
+
+    /**
+     * @param callable(string $slug, int $iteration): string $generator
+     */
+    public function usingSuffixGenerator(callable $generator): self
+    {
+        $this->suffixGenerator = $generator;
+
+        return $this;
+    }
 }

tests/HasSlugTest.php

@@ -335,6 +335,40 @@ public function getSlugOptions(): SlugOptions
     expect($replica->url)->toEqual('this-is-a-test-2');
 });
 
+it('can generate slug suffix on first occurrence', function () {
+    $model = new class () extends TestModel {
+        public function getSlugOptions(): SlugOptions
+        {
+            return parent::getSlugOptions()->useSuffixOnFirstOccurrence();
+        }
+    };
+
+    $model->name = 'this is a test';
+    $model->save();
+
+    expect($model->url)->toEqual('this-is-a-test-1');
+});
+
+it('can generate a custom slug suffix using a callable', function () {
+    $model = new class () extends TestModel {
+        public function getSlugOptions(): SlugOptions
+        {
+            return parent::getSlugOptions()->usingSuffixGenerator(
+                fn(string $slug, int $iteration) => 'random-with-access-base-slug-(' . $slug[0] . '_' . $iteration . ')'
+            );
+        }
+    };
+
+    $model->name = 'this is a test';
+    $model->save();
+
+    $replica = $model->replicate();
+    $replica->save();
+
+    expect($model->url)->toEqual('this-is-a-test');
+    expect($replica->url)->toEqual('this-is-a-test-random-with-access-base-slug-(t_0)');
+});
+
 it('can find models using findBySlug alias', function () {
     $model = new class () extends TestModel {
         public function getSlugOptions(): SlugOptions