Add uniqueCallback option to SluggedBehavior (#312)

Add a new `uniqueCallback` config option that allows customizing the
uniqueness check when generating slugs. This is useful when other
behaviors modify queries (e.g., multi-tenant scoping) and need to be
temporarily disabled during the slug uniqueness check.

The callback receives the Table instance and conditions array, and
must return a boolean indicating whether a matching slug exists.

Fixes #311

Author: dereuromark

docs/Behavior/Slugged.md

@@ -83,6 +83,14 @@ A CakePHP behavior to automatically create and store slugs.
                 </ul>
             </td>
         </tr>
+        <tr>
+            <td>    uniqueCallback    </td>
+            <td> `null`   </td>
+            <td>
+                A closure to customize the uniqueness check. Receives `(Table $table, array $conditions)` and must return `bool`.
+                Useful when other behaviors modify queries (e.g., multi-tenant scoping) and you need to temporarily disable them during the uniqueness check.
+            </td>
+        </tr>
         <tr>
             <td>    case    </td>
             <td> `null`   </td>
@@ -175,4 +183,21 @@ If you quickly want to find a record by its slug, use:
 ```php
 ->find()->find('slugged', slug: $slug)->firstOrFail();
 ```
-etc
+
+### Using a custom uniqueness callback
+If you have other behaviors that modify queries (e.g., multi-tenant scoping), you may need to
+temporarily disable them during the uniqueness check. Use the `uniqueCallback` option:
+
+```php
+$this->addBehavior('Tools.Slugged', [
+    'unique' => true,
+    'uniqueCallback' => function (Table $table, array $conditions): bool {
+        // Temporarily disable a scoping behavior
+        $table->behaviors()->unload('TenantScope');
+        $exists = $table->exists($conditions);
+        $table->behaviors()->load('TenantScope');
+
+        return $exists;
+    },
+]);
+```

src/Model/Behavior/SluggedBehavior.php

@@ -10,6 +10,7 @@
 use Cake\ORM\Query\SelectQuery;
 use Cake\ORM\Table;
 use Cake\Utility\Inflector;
+use Closure;
 use RuntimeException;
 use Shim\Utility\Inflector as ShimInflector;
 
@@ -69,6 +70,7 @@ class SluggedBehavior extends Behavior {
 	 * - on: beforeSave or beforeRules
 	 * - scope: certain conditions to use as scope
 	 * - tidy: If cleanup should be run on slugging
+	 * - uniqueCallback: A closure to customize the uniqueness check. Receives (Table $table, array $conditions) and must return bool.
 	 *
 	 * @var array<string, mixed>
 	 */
@@ -81,6 +83,7 @@ class SluggedBehavior extends Behavior {
 		'length' => null,
 		'overwrite' => false,
 		'unique' => false,
+		'uniqueCallback' => null,
 		'notices' => true,
 		'case' => null,
 		'replace' => [
@@ -426,7 +429,7 @@ public function generateSlug(string $value, ?EntityInterface $entity = null) {
 			$i = 0;
 			$suffix = '';
 
-			while ($this->_table->exists($conditions)) {
+			while ($this->_slugExists($conditions)) {
 				$i++;
 				$suffix = $separator . $i;
 				if ($this->_config['length'] && (mb_strlen($slug . $suffix) > $this->_config['length'])) {
@@ -442,6 +445,25 @@ public function generateSlug(string $value, ?EntityInterface $entity = null) {
 		return $slug;
 	}
 
+	/**
+	 * Check if a slug already exists.
+	 *
+	 * Uses the `uniqueCallback` closure if configured, otherwise falls back to
+	 * the default `exists()` check. This allows customizing the uniqueness check,
+	 * e.g. to temporarily disable other behaviors that might scope the query.
+	 *
+	 * @param array<string, mixed> $conditions The conditions to check for existence.
+	 * @return bool
+	 */
+	protected function _slugExists(array $conditions): bool {
+		$callback = $this->_config['uniqueCallback'];
+		if ($callback instanceof Closure) {
+			return $callback($this->_table, $conditions);
+		}
+
+		return $this->_table->exists($conditions);
+	}
+
 	/**
 	 * Multi slug method
 	 *

tests/TestCase/Model/Behavior/SluggedBehaviorTest.php

@@ -650,6 +650,63 @@ public function testSlugGenerationWithScope() {
 		$this->assertEquals('Some-Article-12345', $result['slug']);
 	}
 
+	/**
+	 * Test unique slug generation with custom callback.
+	 *
+	 * @return void
+	 */
+	public function testUniqueWithCallback() {
+		$callbackInvocations = 0;
+
+		$this->articles->removeBehavior('Slugged');
+		$this->articles->addBehavior('Tools.Slugged', [
+			'unique' => true,
+			'uniqueCallback' => function ($table, $conditions) use (&$callbackInvocations) {
+				$callbackInvocations++;
+
+				return $table->exists($conditions);
+			},
+		]);
+
+		$article = $this->articles->newEntity(['title' => 'Callback Test']);
+		$result = $this->articles->save($article);
+		$this->assertTrue((bool)$result);
+		$this->assertEquals('Callback-Test', $result['slug']);
+		$this->assertSame(1, $callbackInvocations);
+
+		// Second article with same title should trigger multiple callback invocations
+		$article2 = $this->articles->newEntity(['title' => 'Callback Test']);
+		$result2 = $this->articles->save($article2);
+		$this->assertTrue((bool)$result2);
+		$this->assertEquals('Callback-Test-1', $result2['slug']);
+		$this->assertSame(3, $callbackInvocations); // 1 initial + 2 more (first check + suffix check)
+	}
+
+	/**
+	 * Test unique callback that always returns false (no duplicates).
+	 *
+	 * @return void
+	 */
+	public function testUniqueWithCallbackAlwaysFalse() {
+		$this->articles->removeBehavior('Slugged');
+		$this->articles->addBehavior('Tools.Slugged', [
+			'unique' => true,
+			'uniqueCallback' => function ($table, $conditions) {
+				// Always return false = no duplicates found
+				return false;
+			},
+		]);
+
+		$article = $this->articles->newEntity(['title' => 'Always Unique']);
+		$result = $this->articles->save($article);
+		$this->assertEquals('Always-Unique', $result['slug']);
+
+		// Even with same title, callback says no duplicate exists
+		$article2 = $this->articles->newEntity(['title' => 'Always Unique']);
+		$result2 = $this->articles->save($article2);
+		$this->assertEquals('Always-Unique', $result2['slug']); // No suffix added
+	}
+
 	/**
 	 * Test slug generation works with virtual fields.
 	 *