Deprecate annotation-specific properties in the Sluggable extension annotation/attribute classes

Author: mbabker

CHANGELOG.md

@@ -18,6 +18,9 @@ a release.
 ---
 
 ## [Unreleased]
+### Deprecated
+- Sluggable: Annotation-specific mapping parameters (#2837)
+
 ### Fixed
 - Fix regression with `doctrine/dbal` >= 4.0 that caused MariaDB to improperly attempt LONGTEXT casting in `TranslationWalker` (issue #2887)
 

doc/attributes.md

@@ -474,7 +474,8 @@ Optional Parameters:
 
 - **suffix** - An optional suffix for the generated slug
 
-- **handlers** - Unused with attributes
+- **handlers** - Deprecated to be removed in 4.0, this parameter is unused with attributes in favor of
+                 the `SlugHandler` attribute
 
 Basic Example:
 
@@ -552,8 +553,8 @@ class Article
 
 #### `#[Gedmo\Mapping\Annotation\SlugHandlerOption]`
 
-The `SlugHandlerOption` attribute is not supported when using attributes for configuration. Instead, the options
-can be configured directly in the `SlugHandler` attribute's **options** parameter.
+> [!WARNING]
+> The `SlugHandlerOption` attribute is deprecated and will be removed in 4.0. Using this attribute is not supported, and instead, the options can be configured directly in the `SlugHandler` attribute's **options** parameter.
 
 ### Soft Deleteable Extension
 

src/Mapping/Annotation/Slug.php

@@ -44,14 +44,20 @@ final class Slug implements GedmoAnnotation
     public string $separator = '-';
     public string $prefix = '';
     public string $suffix = '';
-    /** @var SlugHandler[] */
+
+    /**
+     * @var SlugHandler[]
+     *
+     * @deprecated since gedmo/doctrine-extensions 3.18
+     */
     public $handlers = [];
+
     public string $dateFormat = 'Y-m-d-H:i';
 
     /**
      * @param array<string, mixed> $data
      * @param string[]             $fields
-     * @param SlugHandler[]        $handlers
+     * @param SlugHandler[]        $handlers @deprecated since since gedmo/doctrine-extensions 3.18
      */
     public function __construct(
         array $data = [],

src/Mapping/Annotation/SlugHandlerOption.php

@@ -21,6 +21,9 @@
  * @NamedArgumentConstructor
  *
  * @author Gediminas Morkevicius <[email protected]>
+ *
+ * @deprecated since gedmo/doctrine-extensions 3.18, will be removed in version 4.0. Configure the options as
+ *             an associative array on the {@see SlugHandler} attribute instead.
  */
 final class SlugHandlerOption implements GedmoAnnotation
 {

src/Sluggable/Mapping/Driver/Attribute.php

@@ -38,6 +38,8 @@ class Attribute extends AbstractAnnotationDriver
 
     /**
      * Mapping object configuring an option for a slug handler.
+     *
+     * @deprecated since gedmo/doctrine-extensions 3.18, will be removed in version 4.0.
      */
     public const HANDLER_OPTION = SlugHandlerOption::class;