[Sluggable] Use TranslationWalker for Translatable objects when looking for similar slugs (#2620)

* fix(Sluggable): Use TranslationWalker for Translatable object when looking for similar slugs

Force translation walker to look for slug translations to avoid duplicated slugs.

---

Fixes #100, fixes #2530

* chore: Added CHANGELOG notice

* chore: Missing issue references to CHANGELOG entry

* chore: Added Sluggable/Issue/Issue100Test

* chore: Rewrite changelog entry and phpstan fix

* feat(Sluggable): Added new option `uniqueOverTranslations` to enable uniqueness across translated slug as well

* chore: Move `$uniqueOverTranslations` new argument at the end for BC

* chore: Missing `uniqueOverTranslations` option in legacy annotation

* docs: Moved Changelog entry to Unreleased section

* Update Changelog

* Fix PHPStan types

* Fix tests

* Make mandatory keys in SlugConfiguration

* Add a check for YAML driver

---------

Co-authored-by: Fran Moreno <[email protected]>

Author: ambroisemaupate

CHANGELOG.md

@@ -23,6 +23,7 @@ a release.
 - Blameable: Allow ascii_string to validTypes (issue #2726)
 - Sluggable: Allow ascii_string to validTypes
 - IpTraceable: Allow ascii_string to validTypes
+- Sluggable: Use `TranslationWalker` hint when looking for similar slugs (`getSimilarSlugs` method) for entities which implement `Translatable` interface and have `uniqueOverTranslations: true` Slug option (#100, #2530)
 
 ## [3.15.0]
 ### Added

doc/sluggable.md

@@ -278,6 +278,7 @@ echo $article->getSlug();
 - **suffix** (optional, default="") - suffix which will be added to the generated slug
 - **style** (optional, default="default") - **"default"** all letters will be lowercase, **"camel"** - first word letter will be uppercase, **"upper"**- all word letter will be uppercase and **"lower"**- all word letter will be lowercase
 - **handlers** (only available in annotations, optional, default=[]) - list of slug handlers, like tree path slug, or customized, for example see bellow
+- **uniqueOverTranslations** (optional, default=false) - **true** if slug should be unique over translations and if identical it will be suffixed, **false** - otherwise
 
 **Note**: handlers are totally optional
 
@@ -584,7 +585,7 @@ class Article
     /**
      * @Gedmo\Translatable
      * @Gedmo\Slug(fields={"title", "code"})
-     * @ORM\Column(length=128, unique=true)
+     * @ORM\Column(length=128, unique=true, uniqueOverTranslations=true)
      */
     private $slug;
 
@@ -595,7 +596,7 @@ class Article
 
     /**
      * @Gedmo\Slug(fields={"uniqueTitle"}, prefix="some-prefix-")
-     * @ORM\Column(type="string", length=128, unique=true)
+     * @ORM\Column(type="string", length=128, unique=true, uniqueOverTranslations=true)
      */
     private $uniqueSlug;
 
@@ -642,6 +643,8 @@ Now the generated slug will be translated by Translatable behavior
 
 <a name="slug-handlers"></a>
 
+`uniqueOverTranslations` option is used to ensure that the slug is unique for each translated slugs.
+
 ## Using slug handlers:
 
 There are built-in slug handlers like described in configuration options of slug, but there

src/Mapping/Annotation/Slug.php

@@ -38,6 +38,7 @@ final class Slug implements GedmoAnnotation
     public bool $updatable = true;
     public string $style = 'default'; // or "camel"
     public bool $unique = true;
+    public bool $uniqueOverTranslations = false;
     /** @var string|null */
     public $unique_base;
     public string $separator = '-';
@@ -63,7 +64,8 @@ public function __construct(
         string $prefix = '',
         string $suffix = '',
         array $handlers = [],
-        string $dateFormat = 'Y-m-d-H:i'
+        string $dateFormat = 'Y-m-d-H:i',
+        bool $uniqueOverTranslations = false
     ) {
         if ([] !== $data) {
             Deprecation::trigger(
@@ -85,6 +87,7 @@ public function __construct(
             $this->suffix = $this->getAttributeValue($data, 'suffix', $args, 8, $suffix);
             $this->handlers = $this->getAttributeValue($data, 'handlers', $args, 9, $handlers);
             $this->dateFormat = $this->getAttributeValue($data, 'dateFormat', $args, 10, $dateFormat);
+            $this->uniqueOverTranslations = $this->getAttributeValue($data, 'uniqueOverTranslations', $args, 11, $uniqueOverTranslations);
 
             return;
         }
@@ -93,6 +96,7 @@ public function __construct(
         $this->updatable = $updatable;
         $this->style = $style;
         $this->unique = $unique;
+        $this->uniqueOverTranslations = $uniqueOverTranslations;
         $this->unique_base = $unique_base;
         $this->separator = $separator;
         $this->prefix = $prefix;

src/Sluggable/Handler/SlugHandlerInterface.php

@@ -20,6 +20,8 @@
  * Sluggable extension and should not be used elsewhere.
  *
  * @author Gediminas Morkevicius <[email protected]>
+ *
+ * @phpstan-import-type SlugConfiguration from SluggableListener
  */
 interface SlugHandlerInterface
 {
@@ -32,10 +34,10 @@ public function __construct(SluggableListener $sluggable);
      * Hook on slug handlers before the decision is made whether
      * the slug needs to be recalculated.
      *
-     * @param array<string, mixed> $config
-     * @param object               $object
-     * @param string               $slug
-     * @param bool                 $needToChangeSlug
+     * @param SlugConfiguration $config
+     * @param object            $object
+     * @param string            $slug
+     * @param bool              $needToChangeSlug
      *
      * @return void
      */
@@ -44,9 +46,9 @@ public function onChangeDecision(SluggableAdapter $ea, array &$config, $object,
     /**
      * Hook on slug handlers called after the slug is built.
      *
-     * @param array<string, mixed> $config
-     * @param object               $object
-     * @param string               $slug
+     * @param SlugConfiguration $config
+     * @param object            $object
+     * @param string            $slug
      *
      * @return void
      */
@@ -55,9 +57,9 @@ public function postSlugBuild(SluggableAdapter $ea, array &$config, $object, &$s
     /**
      * Hook for slug handlers called after the slug is completed.
      *
-     * @param array<string, mixed> $config
-     * @param object               $object
-     * @param string               $slug
+     * @param SlugConfiguration $config
+     * @param object            $object
+     * @param string            $slug
      *
      * @return void
      */

src/Sluggable/Handler/SlugHandlerWithUniqueCallbackInterface.php

@@ -10,22 +10,25 @@
 namespace Gedmo\Sluggable\Handler;
 
 use Gedmo\Sluggable\Mapping\Event\SluggableAdapter;
+use Gedmo\Sluggable\SluggableListener;
 
 /**
  * This adds the ability for a slug handler to change the slug just before its
  * uniqueness is ensured. It is also called if the unique options are _not_
  * set.
  *
  * @author Gediminas Morkevicius <[email protected]>
+ *
+ * @phpstan-import-type SlugConfiguration from SluggableListener
  */
 interface SlugHandlerWithUniqueCallbackInterface extends SlugHandlerInterface
 {
     /**
      * Hook for slug handlers called before it is made unique.
      *
-     * @param array<string, mixed> $config
-     * @param object               $object
-     * @param string               $slug
+     * @param SlugConfiguration $config
+     * @param object            $object
+     * @param string            $slug
      *
      * @return void
      */

src/Sluggable/Mapping/Driver/Annotation.php

@@ -174,12 +174,18 @@ private function retrieveSlug(ClassMetadata $meta, array &$config, \ReflectionPr
         if (!is_bool($slug->unique)) {
             throw new InvalidMappingException("Slug annotation [unique], type is not valid and must be 'boolean' in class - {$meta->getName()}");
         }
+        if (!is_bool($slug->uniqueOverTranslations)) {
+            throw new InvalidMappingException("Slug annotation [uniqueOverTranslations], type is not valid and must be 'boolean' in class - {$meta->getName()}");
+        }
         if ([] !== $meta->getIdentifier() && $meta->isIdentifier($fieldName) && !(bool) $slug->unique) {
             throw new InvalidMappingException("Identifier field - [{$fieldName}] slug must be unique in order to maintain primary key in class - {$meta->getName()}");
         }
         if (false === $slug->unique && $slug->unique_base) {
             throw new InvalidMappingException("Slug annotation [unique_base] can not be set if unique is unset or 'false'");
         }
+        if (false === $slug->unique && $slug->uniqueOverTranslations) {
+            throw new InvalidMappingException("Slug annotation [uniqueOverTranslations] can not be set if unique is unset or 'false'");
+        }
         if ($slug->unique_base && !$meta->hasField($slug->unique_base) && !$meta->hasAssociation($slug->unique_base)) {
             throw new InvalidMappingException("Unable to find [{$slug->unique_base}] as mapped property in entity - {$meta->getName()}");
         }
@@ -201,6 +207,7 @@ private function retrieveSlug(ClassMetadata $meta, array &$config, \ReflectionPr
             'prefix' => $slug->prefix,
             'suffix' => $slug->suffix,
             'handlers' => $handlers,
+            'uniqueOverTranslations' => $slug->uniqueOverTranslations,
         ];
 
         return $config;

src/Sluggable/Mapping/Driver/Xml.php

@@ -144,6 +144,8 @@ private function buildFieldConfiguration(ClassMetadata $meta, string $field, \Si
                 'suffix' => $this->_isAttributeSet($slug, 'suffix') ?
                     $this->_getAttribute($slug, 'suffix') : '',
                 'handlers' => $handlers,
+                'uniqueOverTranslations' => $this->_isAttributeSet($slug, 'uniqueOverTranslations') ?
+                    $this->_getBooleanAttribute($slug, 'uniqueOverTranslations') : false,
             ];
             if (!$meta->isMappedSuperclass && $meta->isIdentifier($field) && !$config['slugs'][$field]['unique']) {
                 throw new InvalidMappingException("Identifier field - [{$field}] slug must be unique in order to maintain primary key in class - {$meta->getName()}");

src/Sluggable/Mapping/Event/Adapter/ORM.php

@@ -10,10 +10,13 @@
 namespace Gedmo\Sluggable\Mapping\Event\Adapter;
 
 use Doctrine\ORM\Mapping\ClassMetadataInfo;
+use Doctrine\ORM\Query;
 use Gedmo\Mapping\Event\Adapter\ORM as BaseAdapterORM;
 use Gedmo\Sluggable\Mapping\Event\SluggableAdapter;
 use Gedmo\Tool\Wrapper\AbstractWrapper;
 use Gedmo\Tool\Wrapper\EntityWrapper;
+use Gedmo\Translatable\Query\TreeWalker\TranslationWalker;
+use Gedmo\Translatable\Translatable;
 
 /**
  * Doctrine event adapter for ORM adapted
@@ -76,7 +79,18 @@ public function getSimilarSlugs($object, $meta, array $config, $slug)
             }
         }
 
-        return $qb->getQuery()->getArrayResult();
+        $query = $qb->getQuery();
+        $query->setHydrationMode(Query::HYDRATE_ARRAY);
+        // Force translation walker to look for slug translations to avoid duplicated slugs
+        // TODO: Remove isset when removing support of YAML driver
+        if (isset($config['uniqueOverTranslations']) && $config['uniqueOverTranslations'] && $object instanceof Translatable) {
+            $query->setHint(
+                Query::HINT_CUSTOM_OUTPUT_WALKER,
+                TranslationWalker::class
+            );
+        }
+
+        return $query->getArrayResult();
     }
 
     public function replaceRelative($object, array $config, $target, $replacement)

src/Sluggable/Mapping/Event/SluggableAdapter.php

@@ -19,6 +19,7 @@
  * @author Gediminas Morkevicius <[email protected]>
  *
  * @phpstan-import-type SluggableConfiguration from SluggableListener
+ * @phpstan-import-type SlugConfiguration from SluggableListener
  */
 interface SluggableAdapter extends AdapterInterface
 {
@@ -29,7 +30,7 @@ interface SluggableAdapter extends AdapterInterface
      * @param ClassMetadata $meta
      * @param string        $slug
      *
-     * @phpstan-param SluggableConfiguration $config
+     * @phpstan-param SlugConfiguration $config
      *
      * @return array<int, array<string, mixed>>
      */
@@ -42,7 +43,7 @@ public function getSimilarSlugs($object, $meta, array $config, $slug);
      * @param string $target
      * @param string $replacement
      *
-     * @phpstan-param SluggableConfiguration $config
+     * @phpstan-param SlugConfiguration $config
      *
      * @return int the number of updated records
      */

src/Sluggable/Sluggable.php

@@ -35,6 +35,7 @@ interface Sluggable
      *         suffix (optional, default="") - suffix which will be added to the generated slug
      *         style (optional, default="default") - "default" all letters will be lowercase, "camel" - first word letter will be uppercase
      *         dateFormat (optional, default="default") - "default" all letters will be lowercase, "camel" - first word letter will be uppercase
+     *         uniqueOverTranslations (optional, default=false) - true if slug should be unique over translations and if identical it will be prefixed, false - otherwise
      *
      * example:
      *