symfony · nicolas-grekas · Dec 19, 2025 · Nov 7, 2025
diff --git a/UPGRADE-8.1.md b/UPGRADE-8.1.md
@@ -1,10 +1,18 @@
 UPGRADE FROM 8.0 to 8.1
 =======================
 
+Symfony 8.1 is a minor release. According to the Symfony release process, there should be no significant
+backward compatibility breaks. Minor backward compatibility breaks are prefixed in this document with
+`[BC BREAK]`, make sure your code is compatible with these entries before upgrading.
+Read more about this in the [Symfony documentation](https://symfony.com/doc/8.1/setup/upgrade_minor.html).
+
+If you're upgrading from a version below 8.0, follow the [8.0 upgrade guide](UPGRADE-8.0.md) first.
+
 DependencyInjection
 -------------------
 
  * Deprecate configuring options `alias`, `parent`, `synthetic`, `file`, `arguments`, `properties`, `configurator` or `calls` when using `from_callable`
+ * Deprecate default index/priority methods when defining tagged locators/iterators; use the `#[AsTaggedItem]` attribute instead
 
 FrameworkBundle
 ---------------

diff --git a/src/Symfony/Component/DependencyInjection/Argument/TaggedIteratorArgument.php b/src/Symfony/Component/DependencyInjection/Argument/TaggedIteratorArgument.php
@@ -21,34 +21,43 @@ class TaggedIteratorArgument extends IteratorArgument
     private mixed $indexAttribute = null;
     private ?string $defaultIndexMethod = null;
     private ?string $defaultPriorityMethod = null;
+    private bool $needsIndexes = false;
+    private array $exclude = [];
+    private bool $excludeSelf = true;
 
     /**
-     * @param string      $tag                   The name of the tag identifying the target services
-     * @param string|null $indexAttribute        The name of the attribute that defines the key referencing each service in the tagged collection
-     * @param string|null $defaultIndexMethod    The static method that should be called to get each service's key when their tag doesn't define the previous attribute
-     * @param bool        $needsIndexes          Whether indexes are required and should be generated when computing the map
-     * @param string|null $defaultPriorityMethod The static method that should be called to get each service's priority when their tag doesn't define the "priority" attribute
-     * @param array       $exclude               Services to exclude from the iterator
-     * @param bool        $excludeSelf           Whether to automatically exclude the referencing service from the iterator
+     * @param string      $tag            The name of the tag identifying the target services
+     * @param string|null $indexAttribute The name of the attribute that defines the key referencing each service in the tagged collection
+     * @param bool        $needsIndexes   Whether indexes are required and should be generated when computing the map
+     * @param string[]    $exclude        Services to exclude from the iterator
+     * @param bool        $excludeSelf    Whether to automatically exclude the referencing service from the iterator
      */
     public function __construct(
         private string $tag,
         ?string $indexAttribute = null,
-        ?string $defaultIndexMethod = null,
-        private bool $needsIndexes = false,
-        ?string $defaultPriorityMethod = null,
-        private array $exclude = [],
-        private bool $excludeSelf = true,
+        bool|string|null $needsIndexes = false,
+        array|bool $exclude = [],
+        bool|string|null $excludeSelf = true,
     ) {
         parent::__construct([]);
 
+        if (\func_num_args() > 5 || !\is_bool($needsIndexes) || !\is_array($exclude) || !\is_bool($excludeSelf)) {
+            [, , $defaultIndexMethod, $needsIndexes, $defaultPriorityMethod, $exclude, $excludeSelf] = \func_get_args() + [2 => null, false, null, [], true];
+            trigger_deprecation('symfony/dependency-injection', '7.4', 'The $defaultIndexMethod and $defaultPriorityMethod arguments of tagged locators and iterators are deprecated, use the #[AsTaggedItem] attribute instead.');
+        } else {
+            $defaultIndexMethod = $defaultPriorityMethod = false;
+        }
+
         if (null === $indexAttribute && $needsIndexes) {
             $indexAttribute = preg_match('/[^.]++$/', $tag, $m) ? $m[0] : $tag;
         }
 
         $this->indexAttribute = $indexAttribute;
         $this->defaultIndexMethod = $defaultIndexMethod ?: ($indexAttribute ? 'getDefault'.str_replace(' ', '', ucwords(preg_replace('/[^a-zA-Z0-9\x7f-\xff]++/', ' ', $indexAttribute))).'Name' : null);
         $this->defaultPriorityMethod = $defaultPriorityMethod ?: ($indexAttribute ? 'getDefault'.str_replace(' ', '', ucwords(preg_replace('/[^a-zA-Z0-9\x7f-\xff]++/', ' ', $indexAttribute))).'Priority' : null);
+        $this->needsIndexes = $needsIndexes;
+        $this->exclude = $exclude;
+        $this->excludeSelf = $excludeSelf;
     }
 
     public function getTag(): string
@@ -61,8 +70,15 @@ public function getIndexAttribute(): ?string
         return $this->indexAttribute;
     }
 
-    public function getDefaultIndexMethod(): ?string
+    /**
+     * @deprecated since Symfony 8.1, use the #[AsTaggedItem] attribute instead of default methods
+     */
+    public function getDefaultIndexMethod(/* bool $triggerDeprecation = true */): ?string
     {
+        if (!\func_num_args() || func_get_arg(0)) {
+            trigger_deprecation('symfony/dependency-injection', '7.4', 'The "%s()" method is deprecated, use the #[AsTaggedItem] attribute instead of default methods.', __METHOD__);
+        }
+
         return $this->defaultIndexMethod;
     }
 
@@ -71,8 +87,15 @@ public function needsIndexes(): bool
         return $this->needsIndexes;
     }
 
-    public function getDefaultPriorityMethod(): ?string
+    /**
+     * @deprecated since Symfony 8.1, use the #[AsTaggedItem] attribute instead of default methods
+     */
+    public function getDefaultPriorityMethod(/* bool $triggerDeprecation = true */): ?string
     {
+        if (!\func_num_args() || func_get_arg(0)) {
+            trigger_deprecation('symfony/dependency-injection', '7.4', 'The "%s()" method is deprecated, use the #[AsTaggedItem] attribute instead of default methods.', __METHOD__);
+        }
+
         return $this->defaultPriorityMethod;
     }
 

diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AutowireIterator.php b/src/Symfony/Component/DependencyInjection/Attribute/AutowireIterator.php
@@ -22,21 +22,31 @@
     /**
      * @see ServiceSubscriberInterface::getSubscribedServices()
      *
-     * @param string               $tag                   A tag name to search for to populate the iterator
-     * @param string|null          $indexAttribute        The name of the attribute that defines the key referencing each service in the tagged collection
-     * @param string|null          $defaultIndexMethod    The static method that should be called to get each service's key when their tag doesn't define the previous attribute
-     * @param string|null          $defaultPriorityMethod The static method that should be called to get each service's priority when their tag doesn't define the "priority" attribute
-     * @param string|array<string> $exclude               A service id or a list of service ids to exclude
-     * @param bool                 $excludeSelf           Whether to automatically exclude the referencing service from the iterator
+     * @param string          $tag            A tag name to search for to populate the iterator
+     * @param string|null     $indexAttribute The name of the attribute that defines the key referencing each service in the tagged collection
+     * @param string|string[] $exclude        A service id or a list of service ids to exclude
+     * @param bool            $excludeSelf    Whether to automatically exclude the referencing service from the iterator
      */
     public function __construct(
         string $tag,
         ?string $indexAttribute = null,
-        ?string $defaultIndexMethod = null,
-        ?string $defaultPriorityMethod = null,
-        string|array $exclude = [],
-        bool $excludeSelf = true,
+        string|array|null $exclude = [],
+        bool|string|null $excludeSelf = true,
+        ...$_,
     ) {
-        parent::__construct(new TaggedIteratorArgument($tag, $indexAttribute, $defaultIndexMethod, false, $defaultPriorityMethod, (array) $exclude, $excludeSelf));
+        if (\func_num_args() > 4 || !\is_bool($excludeSelf) || null === $exclude || (\is_string($exclude) && str_starts_with($exclude, 'get') && !\array_key_exists('defaultIndexMethod', $_))) {
+            [, , $defaultIndexMethod, $defaultPriorityMethod, $exclude, $excludeSelf] = \func_get_args() + [2 => null, null, [], true];
+        } else {
+            $defaultIndexMethod = \array_key_exists('defaultIndexMethod', $_) ? $_['defaultIndexMethod'] : false;
+            $defaultPriorityMethod = \array_key_exists('defaultPriorityMethod', $_) ? $_['defaultPriorityMethod'] : false;
+        }
+
+        if (false !== $defaultIndexMethod || false !== $defaultPriorityMethod) {
+            parent::__construct(new TaggedIteratorArgument($tag, $indexAttribute, $defaultIndexMethod, false, $defaultPriorityMethod, (array) $exclude, $excludeSelf));
+
+            return;
+        }
+
+        parent::__construct(new TaggedIteratorArgument($tag, $indexAttribute, false, (array) $exclude, $excludeSelf));
     }
 }
diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AutowireLocator.php b/src/Symfony/Component/DependencyInjection/Attribute/AutowireLocator.php
@@ -28,26 +28,38 @@
     /**
      * @see ServiceSubscriberInterface::getSubscribedServices()
      *
-     * @param string|array<string|Autowire|SubscribedService> $services              A tag name or an explicit list of service ids
-     * @param string|null                                     $indexAttribute        The name of the attribute that defines the key referencing each service in the locator
-     * @param string|null                                     $defaultIndexMethod    The static method that should be called to get each service's key when their tag doesn't define the previous attribute
-     * @param string|null                                     $defaultPriorityMethod The static method that should be called to get each service's priority when their tag doesn't define the "priority" attribute
-     * @param string|array                                    $exclude               A service id or a list of service ids to exclude
-     * @param bool                                            $excludeSelf           Whether to automatically exclude the referencing service from the locator
+     * @param string|array<string|Autowire|SubscribedService> $services       A tag name or an explicit list of service ids
+     * @param string|null                                     $indexAttribute The name of the attribute that defines the key referencing each service in the locator
+     * @param string|string[]                                 $exclude        A service id or a list of service ids to exclude
+     * @param bool                                            $excludeSelf    Whether to automatically exclude the referencing service from the locator
      */
     public function __construct(
         string|array $services,
         ?string $indexAttribute = null,
-        ?string $defaultIndexMethod = null,
-        ?string $defaultPriorityMethod = null,
-        string|array $exclude = [],
-        bool $excludeSelf = true,
+        string|array|null $exclude = [],
+        bool|string|null $excludeSelf = true,
+        ...$_,
     ) {
+        if (\func_num_args() > 4 || !\is_bool($excludeSelf) || null === $exclude || (\is_string($exclude) && str_starts_with($exclude, 'get') && !\array_key_exists('defaultIndexMethod', $_))) {
+            [, , $defaultIndexMethod, $defaultPriorityMethod, $exclude, $excludeSelf] = \func_get_args() + [2 => null, null, [], true];
+        } else {
+            $defaultIndexMethod = \array_key_exists('defaultIndexMethod', $_) ? $_['defaultIndexMethod'] : false;
+            $defaultPriorityMethod = \array_key_exists('defaultPriorityMethod', $_) ? $_['defaultPriorityMethod'] : false;
+        }
+
         if (\is_string($services)) {
-            parent::__construct(new ServiceLocatorArgument(new TaggedIteratorArgument($services, $indexAttribute, $defaultIndexMethod, true, $defaultPriorityMethod, (array) $exclude, $excludeSelf)));
+            if (false !== $defaultIndexMethod || false !== $defaultPriorityMethod) {
+                parent::__construct(new ServiceLocatorArgument(new TaggedIteratorArgument($services, $indexAttribute, $defaultIndexMethod, true, $defaultPriorityMethod, (array) $exclude, $excludeSelf)));
+
+                return;
+            }
+            parent::__construct(new ServiceLocatorArgument(new TaggedIteratorArgument($services, $indexAttribute, true, (array) $exclude, $excludeSelf)));
 
             return;
         }
+        if (false !== $defaultIndexMethod || false !== $defaultPriorityMethod) {
+            trigger_deprecation('symfony/dependency-injection', '7.4', 'The $defaultIndexMethod and $defaultPriorityMethod arguments of tagged locators and iterators attributes are deprecated, use the #[AsTaggedItem] attribute instead of default methods.');
+        }
 
         $references = [];
 

diff --git a/src/Symfony/Component/DependencyInjection/CHANGELOG.md b/src/Symfony/Component/DependencyInjection/CHANGELOG.md
@@ -5,6 +5,7 @@ CHANGELOG
 ---
 
  * Deprecate configuring options `alias`, `parent`, `synthetic`, `file`, `arguments`, `properties`, `configurator` or `calls` when using `from_callable`
+ * Deprecate default index/priority methods when defining tagged locators/iterators; use the `#[AsTaggedItem]` attribute instead
 
 8.0
 ---

diff --git a/src/Symfony/Component/DependencyInjection/Compiler/PriorityTaggedServiceTrait.php b/src/Symfony/Component/DependencyInjection/Compiler/PriorityTaggedServiceTrait.php
@@ -43,9 +43,9 @@ private function findAndSortTaggedServices(string|TaggedIteratorArgument $tagNam
 
         if ($tagName instanceof TaggedIteratorArgument) {
             $indexAttribute = $tagName->getIndexAttribute();
-            $defaultIndexMethod = $tagName->getDefaultIndexMethod();
+            $defaultIndexMethod = $tagName->getDefaultIndexMethod(false);
             $needsIndexes = $tagName->needsIndexes();
-            $defaultPriorityMethod = $tagName->getDefaultPriorityMethod() ?? 'getDefaultPriority';
+            $defaultPriorityMethod = $tagName->getDefaultPriorityMethod(false) ?? 'getDefaultPriority';
             $exclude = array_merge($exclude, $tagName->getExclude());
             $tagName = $tagName->getTag();
         }
@@ -163,6 +163,8 @@ public static function getDefault(string $serviceId, \ReflectionClass $r, string
             throw new InvalidArgumentException(implode('be public', $message));
         }
 
+        trigger_deprecation('symfony/dependency-injection', '7.4', 'Calling "%s::%s()" to get the "%s" index is deprecated, use the #[AsTaggedItem] attribute instead.', $class, $defaultMethod, $indexAttribute);
+
         $default = $rm->invoke(null);
 
         if ('priority' === $indexAttribute) {

diff --git a/src/Symfony/Component/DependencyInjection/Dumper/XmlDumper.php b/src/Symfony/Component/DependencyInjection/Dumper/XmlDumper.php
@@ -308,11 +308,13 @@ private function convertParameters(array $parameters, string $type, string $keyA
                 if (null !== $tag->getIndexAttribute()) {
                     $xmlAttr .= \sprintf(' index-by="%s"', $this->encode($tag->getIndexAttribute()));
 
-                    if (null !== $tag->getDefaultIndexMethod()) {
-                        $xmlAttr .= \sprintf(' default-index-method="%s"', $this->encode($tag->getDefaultIndexMethod()));
+                    $defaultPrefix = 'getDefault'.str_replace(' ', '', ucwords(preg_replace('/[^a-zA-Z0-9\x7f-\xff]++/', ' ', $tag->getIndexAttribute())));
+
+                    if ($tag->getDefaultIndexMethod(false) !== $defaultPrefix.'Name') {
+                        $xmlAttr .= \sprintf(' default-index-method="%s"', $this->encode($tag->getDefaultIndexMethod(false)));
                     }
-                    if (null !== $tag->getDefaultPriorityMethod()) {
-                        $xmlAttr .= \sprintf(' default-priority-method="%s"', $this->encode($tag->getDefaultPriorityMethod()));
+                    if ($tag->getDefaultPriorityMethod(false) !== $defaultPrefix.'Priority') {
+                        $xmlAttr .= \sprintf(' default-priority-method="%s"', $this->encode($tag->getDefaultPriorityMethod(false)));
                     }
                 }
                 if (1 === \count($excludes = $tag->getExclude())) {

diff --git a/src/Symfony/Component/DependencyInjection/Dumper/YamlDumper.php b/src/Symfony/Component/DependencyInjection/Dumper/YamlDumper.php
@@ -265,11 +265,11 @@ private function dumpValue(mixed $value): mixed
                         'index_by' => $tag->getIndexAttribute(),
                     ];
 
-                    if (null !== $tag->getDefaultIndexMethod()) {
-                        $content['default_index_method'] = $tag->getDefaultIndexMethod();
+                    if (null !== $tag->getDefaultIndexMethod(false)) {
+                        $content['default_index_method'] = $tag->getDefaultIndexMethod(false);
                     }
-                    if (null !== $tag->getDefaultPriorityMethod()) {
-                        $content['default_priority_method'] = $tag->getDefaultPriorityMethod();
+                    if (null !== $tag->getDefaultPriorityMethod(false)) {
+                        $content['default_priority_method'] = $tag->getDefaultPriorityMethod(false);
                     }
                 }
                 if ($excludes = $tag->getExclude()) {
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,6 +5,7 @@ CHANGELOG @@
     ---
      * Deprecate configuring options `alias`, `parent`, `synthetic`, `file`, `arguments`, `properties`, `configurator` or `calls` when using `from_callable`
+     * Deprecate default index/priority methods when defining tagged locators/iterators; use the `#[AsTaggedItem]` attribute instead
 .0
     ---
@@ Expand Down @@