Make ancestorClass option consistency to underscore

composer.json

@@ -20,7 +20,8 @@
         }
     ],
     "require": {
-        "php": "^7.2 || ^8.0"
+        "php": "^7.2 || ^8.0",
+        "symfony/deprecation-contracts": "^2.4"
     },
     "conflict": {
         "twig/twig": "<1.40 || >=2,<2.9"

doc/01-Basic-Menus.md

@@ -238,7 +238,7 @@ the second argument to the `render()` method:
   is an ancestor of the current item.
 * `currentAsLink` (default: `true`): Whether to render the "current" menu item as link or as span.
 * `currentClass` (default: `current`)
-* `ancestorClass` (default: `current_ancestor`)
+* `ancestor_class` (default: `current_ancestor`) (alias: ancestorClass, currently deprecated)
 * `firstClass` (default: `first`)
 * `lastClass` (default:  `last`)
 * `compressed` (default: `false`)

doc/examples/01_apply_active_class_to_whole_tree.md

@@ -5,6 +5,13 @@ By default the active menu item is applied with a `current` class and it's ances
 class. To apply a class other than the default or apply the same class to both you can either pass it as option to the 
 render method of your used renderer:
 
+```php
+<?php
+$renderer->render($item, ['currentClass' => 'active', 'ancestor_class' => 'active']);
+```
+
+Old deprecated way:
+
 ```php
 <?php
 $renderer->render($item, ['currentClass' => 'active', 'ancestorClass' => 'active']);
@@ -14,5 +21,12 @@ or pass it as argument to the constructor of the used renderer:
 
 ```php
 <?php
-$renderer = new Renderer($matcher, ['currentClass' => 'active', 'ancestorClass' => 'active']);
+$renderer = new Renderer($matcher, ['currentClass' => 'active', 'ancestor_class' => 'active']);
+```
+
+Old deprecated way:
+
+```php
+<?php
+$renderer = new Renderer($matcher, ['currentClass' => 'active', 'ancestorClass' => 'active'])
 ```

src/Knp/Menu/Renderer/ListRenderer.php

@@ -31,7 +31,8 @@ public function __construct(MatcherInterface $matcher, array $defaultOptions = [
             'matchingDepth' => null,
             'currentAsLink' => true,
             'currentClass' => 'current',
-            'ancestorClass' => 'current_ancestor',
+            'ancestor_class' => 'current_ancestor',
+            'ancestorClass' => 'current_ancestor', // Deprecated in future
             'firstClass' => 'first',
             'lastClass' => 'last',
             'compressed' => false,
@@ -130,7 +131,11 @@ protected function renderItem(ItemInterface $item, array $options): string
         if ($this->matcher->isCurrent($item)) {
             $class[] = $options['currentClass'];
         } elseif ($this->matcher->isAncestor($item, $options['matchingDepth'])) {
-            $class[] = $options['ancestorClass'];
+            if(isset($options['ancestorClass']) { // Deprecated: it will be removed in future (@see: ancestor_class)
+                trigger_deprecation('knplabs/knp-menu', '3.2', 'Using "%s" option is deprecated, use "%s" instead.', 'ancestorClass', 'ancestor_class');
+                $options['ancestor_class'] = $options['ancestorClass'];
+            }
+            $class[] = $options['ancestor_class'];
         }
 
         if ($item->actsLikeFirst()) {

src/Knp/Menu/Renderer/RendererInterface.php

@@ -16,7 +16,7 @@ interface RendererInterface
      *          1: only direct children
      *      - currentAsLink: whether the current item should be a link
      *      - currentClass: class added to the current item
-     *      - ancestorClass: class added to the ancestors of the current item
+     *      - ancestor_class: class added to the ancestors of the current item (alias: ancestorClass, deprecated in a future)
      *      - firstClass: class added to the first child
      *      - lastClass: class added to the last child
      *

src/Knp/Menu/Renderer/TwigRenderer.php

@@ -39,6 +39,7 @@ public function __construct(
             'matchingDepth' => null,
             'currentAsLink' => true,
             'currentClass' => 'current',
+            'ancestor_class' => 'current_ancestor',
             'ancestorClass' => 'current_ancestor',
             'firstClass' => 'first',
             'lastClass' => 'last',

src/Knp/Menu/Resources/views/knp_menu.html.twig

@@ -55,7 +55,8 @@
     {%- if matcher.isCurrent(item) %}
         {%- set classes = classes|merge([options.currentClass]) %}
     {%- elseif matcher.isAncestor(item, options.matchingDepth) %}
-        {%- set classes = classes|merge([options.ancestorClass]) %}
+        {# ancestorClass will be deprecated in future, use ancestor_class #}
+        {%- set classes = classes|merge([options.ancestor_class])|merge([options.ancestorClass]) %}
     {%- endif %}
     {%- if item.actsLikeFirst %}
         {%- set classes = classes|merge([options.firstClass]) %}