From aeb0856a1cd966767ddbc9151162577d1694f454 Mon Sep 17 00:00:00 2001
From: Dmitriy Derepko <xepozz@list.ru>
Date: Fri, 23 Feb 2024 14:23:36 +0700
Subject: [PATCH] Fix #353: Add shortcut for tag reference #333

---
 CHANGELOG.md                              |  2 +-
 README.md                                 |  7 ++-
 src/CompositeContainer.php                |  4 +-
 src/Container.php                         | 10 +--
 src/Helpers/TagHelper.php                 | 21 -------
 src/Reference/TagReference.php            | 38 ++++++++++++
 tests/Unit/Reference/TagReferenceTest.php | 76 +++++++++++++++++++++++
 7 files changed, 126 insertions(+), 32 deletions(-)
 delete mode 100644 src/Helpers/TagHelper.php
 create mode 100644 src/Reference/TagReference.php
 create mode 100644 tests/Unit/Reference/TagReferenceTest.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c11cac6d..76121f14 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 ## 1.2.2 under development
 
-- no changes in this release.
+- Enh #353: Add shortcut for tag reference #333 (@xepozz)
 
 ## 1.2.1 December 23, 2022
 
diff --git a/README.md b/README.md
index 0e8a3665..e2a2f0fc 100644
--- a/README.md
+++ b/README.md
@@ -315,7 +315,7 @@ $container = new Container($config);
 Now you can get tagged services from the container in the following way:
 
 ```php
-$container->get('tag@car');
+$container->get(\Yiisoft\Di\Reference\TagReference::to('car'));
 ```
 
 The result is an array that has two instances: `BlueCarService` and `RedCarService`.
@@ -504,8 +504,9 @@ $container = new Container($config);
 
 To run benchmarks execute the next command
 
-`composer require phpbench/phpbench` 
-`$ ./vendor/bin/phpbench run`
+```shell
+./vendor/bin/phpbench run
+```
 
 Result example
 
diff --git a/src/CompositeContainer.php b/src/CompositeContainer.php
index b921bc0f..f3d99e29 100644
--- a/src/CompositeContainer.php
+++ b/src/CompositeContainer.php
@@ -8,7 +8,7 @@
 use Psr\Container\ContainerInterface;
 use RuntimeException;
 use Throwable;
-use Yiisoft\Di\Helpers\TagHelper;
+use Yiisoft\Di\Reference\TagReference;
 
 use function is_string;
 
@@ -54,7 +54,7 @@ public function get($id)
             return $stateResetter;
         }
 
-        if (TagHelper::isTagAlias($id)) {
+        if (TagReference::isTagAlias($id)) {
             $tags = [];
             foreach ($this->containers as $container) {
                 if (!$container instanceof Container) {
diff --git a/src/Container.php b/src/Container.php
index 45065e0a..f29df055 100644
--- a/src/Container.php
+++ b/src/Container.php
@@ -17,7 +17,7 @@
 use Yiisoft\Definitions\Helpers\DefinitionValidator;
 use Yiisoft\Di\Helpers\DefinitionNormalizer;
 use Yiisoft\Di\Helpers\DefinitionParser;
-use Yiisoft\Di\Helpers\TagHelper;
+use Yiisoft\Di\Reference\TagReference;
 
 use function array_key_exists;
 use function array_keys;
@@ -101,8 +101,8 @@ public function __construct(ContainerConfigInterface $config)
      */
     public function has(string $id): bool
     {
-        if (TagHelper::isTagAlias($id)) {
-            $tag = TagHelper::extractTagFromAlias($id);
+        if (TagReference::isTagAlias($id)) {
+            $tag = TagReference::extractTagFromAlias($id);
             return isset($this->tags[$tag]);
         }
 
@@ -472,7 +472,7 @@ private function addDefinitionToStorage(string $id, $definition): void
      */
     private function build(string $id)
     {
-        if (TagHelper::isTagAlias($id)) {
+        if (TagReference::isTagAlias($id)) {
             return $this->getTaggedServices($id);
         }
 
@@ -502,7 +502,7 @@ private function build(string $id)
 
     private function getTaggedServices(string $tagAlias): array
     {
-        $tag = TagHelper::extractTagFromAlias($tagAlias);
+        $tag = TagReference::extractTagFromAlias($tagAlias);
         $services = [];
         if (isset($this->tags[$tag])) {
             foreach ($this->tags[$tag] as $service) {
diff --git a/src/Helpers/TagHelper.php b/src/Helpers/TagHelper.php
deleted file mode 100644
index d38c089e..00000000
--- a/src/Helpers/TagHelper.php
+++ /dev/null
@@ -1,21 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Yiisoft\Di\Helpers;
-
-/**
- * @internal
- */
-final class TagHelper
-{
-    public static function extractTagFromAlias(string $alias): string
-    {
-        return substr($alias, 4);
-    }
-
-    public static function isTagAlias(string $id): bool
-    {
-        return str_starts_with($id, 'tag@');
-    }
-}
diff --git a/src/Reference/TagReference.php b/src/Reference/TagReference.php
new file mode 100644
index 00000000..d3dcbf66
--- /dev/null
+++ b/src/Reference/TagReference.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Di\Reference;
+
+use Yiisoft\Definitions\Reference;
+
+/**
+ * TagReference is a helper class that is used to specify a reference to a tag.
+ * For example, `TagReference::to('my-tag')` specifies a reference to all services that are tagged with `tag@my-tag`.
+ */
+final class TagReference
+{
+    private const PREFIX = 'tag@';
+
+    private function __construct()
+    {
+    }
+
+    public static function to(string $tag): Reference
+    {
+        return Reference::to(self::PREFIX . $tag);
+    }
+
+    public static function extractTagFromAlias(string $alias): string
+    {
+        if (!str_starts_with($alias, self::PREFIX)) {
+            throw new \InvalidArgumentException(sprintf('Alias "%s" is not a tag alias.', $alias));
+        }
+        return substr($alias, 4);
+    }
+
+    public static function isTagAlias(string $id): bool
+    {
+        return str_starts_with($id, self::PREFIX);
+    }
+}
diff --git a/tests/Unit/Reference/TagReferenceTest.php b/tests/Unit/Reference/TagReferenceTest.php
new file mode 100644
index 00000000..9abfe046
--- /dev/null
+++ b/tests/Unit/Reference/TagReferenceTest.php
@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Di\Tests\Unit\Reference;
+
+use Error;
+use InvalidArgumentException;
+use PHPUnit\Framework\TestCase;
+use Psr\Container\ContainerInterface;
+use Yiisoft\Di\Reference\TagReference;
+
+final class TagReferenceTest extends TestCase
+{
+    public function testConstructorIsPrivate(): void
+    {
+        $this->expectException(Error::class);
+        new TagReference();
+    }
+
+    public function testConstructor(): void
+    {
+        $reflection = new \ReflectionClass(TagReference::class);
+        $reflectionMethod = $reflection->getConstructor();
+        $this->assertTrue($reflectionMethod->isPrivate());
+        if (PHP_VERSION_ID < 81000) {
+            $reflectionMethod->setAccessible(true);
+        }
+
+        $reflectionMethod->invoke($reflection->newInstanceWithoutConstructor());
+    }
+
+    public function testAliases(): void
+    {
+        $this->assertFalse(TagReference::isTagAlias('test'));
+        $this->assertFalse(TagReference::isTagAlias('tag#test'));
+        $this->assertTrue(TagReference::isTagAlias('tag@test'));
+    }
+
+    public function testExtractTag(): void
+    {
+        $this->assertEquals('test', TagReference::extractTagFromAlias('tag@test'));
+    }
+
+    public function testExtractWrongTagDelimiter(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        TagReference::extractTagFromAlias('tag#test');
+    }
+
+    public function testExtractWrongTagFormat(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        TagReference::extractTagFromAlias('test');
+    }
+
+    public function testReference(): void
+    {
+        $reference = TagReference::to('test');
+        $spyContainer = new class () implements ContainerInterface {
+            public function get($id)
+            {
+                return $id;
+            }
+
+            public function has($id): bool
+            {
+                return true;
+            }
+        };
+
+        $result = $reference->resolve($spyContainer);
+
+        $this->assertEquals('tag@test', $result);
+    }
+}