[Contracts] Rename ServiceSubscriberTrait to ServiceMethodsSubscriberTrait

Author: nicolas-grekas

CHANGELOG.md

@@ -5,6 +5,7 @@ CHANGELOG
 ---
 
  * Add `ServiceCollectionInterface`
+ * Deprecate `ServiceSubscriberTrait`, use `ServiceMethodsSubscriberTrait` instead
 
 3.4
 ---

Service/Attribute/SubscribedService.php

@@ -11,15 +11,15 @@
 
 namespace Symfony\Contracts\Service\Attribute;
 
+use Symfony\Contracts\Service\ServiceMethodsSubscriberTrait;
 use Symfony\Contracts\Service\ServiceSubscriberInterface;
-use Symfony\Contracts\Service\ServiceSubscriberTrait;
 
 /**
  * For use as the return value for {@see ServiceSubscriberInterface}.
  *
  * @example new SubscribedService('http_client', HttpClientInterface::class, false, new Target('githubApi'))
  *
- * Use with {@see ServiceSubscriberTrait} to mark a method's return type
+ * Use with {@see ServiceMethodsSubscriberTrait} to mark a method's return type
  * as a subscribed service.
  *
  * @author Kevin Bond <[email protected]>

Service/ServiceMethodsSubscriberTrait.php

@@ -0,0 +1,80 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Contracts\Service;
+
+use Psr\Container\ContainerInterface;
+use Symfony\Contracts\Service\Attribute\Required;
+use Symfony\Contracts\Service\Attribute\SubscribedService;
+
+/**
+ * Implementation of ServiceSubscriberInterface that determines subscribed services
+ * from methods that have the #[SubscribedService] attribute.
+ *
+ * Service ids are available as "ClassName::methodName" so that the implementation
+ * of subscriber methods can be just `return $this->container->get(__METHOD__);`.
+ *
+ * @author Kevin Bond <[email protected]>
+ */
+trait ServiceMethodsSubscriberTrait
+{
+    protected ContainerInterface $container;
+
+    public static function getSubscribedServices(): array
+    {
+        $services = method_exists(get_parent_class(self::class) ?: '', __FUNCTION__) ? parent::getSubscribedServices() : [];
+
+        foreach ((new \ReflectionClass(self::class))->getMethods() as $method) {
+            if (self::class !== $method->getDeclaringClass()->name) {
+                continue;
+            }
+
+            if (!$attribute = $method->getAttributes(SubscribedService::class)[0] ?? null) {
+                continue;
+            }
+
+            if ($method->isStatic() || $method->isAbstract() || $method->isGenerator() || $method->isInternal() || $method->getNumberOfRequiredParameters()) {
+                throw new \LogicException(sprintf('Cannot use "%s" on method "%s::%s()" (can only be used on non-static, non-abstract methods with no parameters).', SubscribedService::class, self::class, $method->name));
+            }
+
+            if (!$returnType = $method->getReturnType()) {
+                throw new \LogicException(sprintf('Cannot use "%s" on methods without a return type in "%s::%s()".', SubscribedService::class, $method->name, self::class));
+            }
+
+            /* @var SubscribedService $attribute */
+            $attribute = $attribute->newInstance();
+            $attribute->key ??= self::class.'::'.$method->name;
+            $attribute->type ??= $returnType instanceof \ReflectionNamedType ? $returnType->getName() : (string) $returnType;
+            $attribute->nullable = $returnType->allowsNull();
+
+            if ($attribute->attributes) {
+                $services[] = $attribute;
+            } else {
+                $services[$attribute->key] = ($attribute->nullable ? '?' : '').$attribute->type;
+            }
+        }
+
+        return $services;
+    }
+
+    #[Required]
+    public function setContainer(ContainerInterface $container): ?ContainerInterface
+    {
+        $ret = null;
+        if (method_exists(get_parent_class(self::class) ?: '', __FUNCTION__)) {
+            $ret = parent::setContainer($container);
+        }
+
+        $this->container = $container;
+
+        return $ret;
+    }
+}

Service/ServiceSubscriberTrait.php

@@ -15,17 +15,23 @@
 use Symfony\Contracts\Service\Attribute\Required;
 use Symfony\Contracts\Service\Attribute\SubscribedService;
 
+trigger_deprecation('symfony/contracts', 'v3.5', '"%s" is deprecated, use "ServiceMethodsSubscriberTrait" instead.', ServiceSubscriberTrait::class);
+
 /**
- * Implementation of ServiceSubscriberInterface that determines subscribed services from
- * method return types. Service ids are available as "ClassName::methodName".
+ * Implementation of ServiceSubscriberInterface that determines subscribed services
+ * from methods that have the #[SubscribedService] attribute.
+ *
+ * Service ids are available as "ClassName::methodName" so that the implementation
+ * of subscriber methods can be just `return $this->container->get(__METHOD__);`.
+ *
+ * @property ContainerInterface $container
  *
  * @author Kevin Bond <[email protected]>
+ *
+ * @deprecated since symfony/contracts v3.5, use ServiceMethodsSubscriberTrait instead
  */
 trait ServiceSubscriberTrait
 {
-    /** @var ContainerInterface */
-    protected $container;
-
     public static function getSubscribedServices(): array
     {
         $services = method_exists(get_parent_class(self::class) ?: '', __FUNCTION__) ? parent::getSubscribedServices() : [];

Service/composer.json

@@ -17,7 +17,8 @@
     ],
     "require": {
         "php": ">=8.1",
-        "psr/container": "^1.1|^2.0"
+        "psr/container": "^1.1|^2.0",
+        "symfony/deprecation-contracts": "^2.5|^3"
     },
     "conflict": {
         "ext-psr": "<1.1|>=2"

Tests/Service/LegacyTestService.php

@@ -0,0 +1,93 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Contracts\Tests\Service;
+
+use Psr\Container\ContainerInterface;
+use Symfony\Contracts\Service\Attribute\Required;
+use Symfony\Contracts\Service\Attribute\SubscribedService;
+use Symfony\Contracts\Service\ServiceSubscriberInterface;
+use Symfony\Contracts\Service\ServiceSubscriberTrait;
+
+class LegacyParentTestService
+{
+    public function aParentService(): Service1
+    {
+    }
+
+    public function setContainer(ContainerInterface $container): ?ContainerInterface
+    {
+        return $container;
+    }
+}
+
+class LegacyTestService extends LegacyParentTestService implements ServiceSubscriberInterface
+{
+    use ServiceSubscriberTrait;
+
+    #[SubscribedService]
+    public function aService(): Service2
+    {
+        return $this->container->get(__METHOD__);
+    }
+
+    #[SubscribedService]
+    public function nullableService(): ?Service2
+    {
+        return $this->container->get(__METHOD__);
+    }
+
+    #[SubscribedService(attributes: new Required())]
+    public function withAttribute(): ?Service2
+    {
+        return $this->container->get(__METHOD__);
+    }
+}
+
+class LegacyChildTestService extends LegacyTestService
+{
+    #[SubscribedService()]
+    public function aChildService(): LegacyService3
+    {
+        return $this->container->get(__METHOD__);
+    }
+}
+
+class LegacyParentWithMagicCall
+{
+    public function __call($method, $args)
+    {
+        throw new \BadMethodCallException('Should not be called.');
+    }
+
+    public static function __callStatic($method, $args)
+    {
+        throw new \BadMethodCallException('Should not be called.');
+    }
+}
+
+class LegacyService3
+{
+}
+
+class LegacyParentTestService2
+{
+    /** @var ContainerInterface */
+    protected $container;
+
+    public function setContainer(ContainerInterface $container)
+    {
+        $previous = $this->container ?? null;
+        $this->container = $container;
+
+        return $previous;
+    }
+}