Add TagReference::id() method + Improve docs (#380)

* Add `TagReference::makeId()` method + Improve docs

* Apply fixes from StyleCI

* Update README.md

Co-authored-by: Alexey Rogachev <[email protected]>

* Update README.md

Co-authored-by: Alexey Rogachev <[email protected]>

* Update README.md

Co-authored-by: Alexey Rogachev <[email protected]>

* Update src/Reference/TagReference.php

Co-authored-by: Alexey Rogachev <[email protected]>

* Update src/Reference/TagReference.php

Co-authored-by: Alexander Makarov <[email protected]>

* fix

---------

Co-authored-by: StyleCI Bot <[email protected]>
Co-authored-by: Alexey Rogachev <[email protected]>
Co-authored-by: Alexander Makarov <[email protected]>

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 1.3.1 under development
 
-- no changes in this release.
+- New #380: Add `TagReference::id()` method (@vjik)
 
 ## 1.3.0 October 14, 2024
 

README.md

@@ -338,14 +338,6 @@ $config = ContainerConfig::create()
 $container = new Container($config);
 ```
 
-Now you can get tagged services from the container in the following way:
-
-```php
-$container->get(\Yiisoft\Di\Reference\TagReference::to('car'));
-```
-
-The result is an array that has two instances: `BlueCarService` and `RedCarService`.
-
 Another way to tag services is setting tags via container constructor:
 
 ```php
@@ -367,6 +359,30 @@ $config = ContainerConfig::create()
 $container = new Container($config);
 ```
 
+### Getting tagged services
+
+You can get tagged services from the container in the following way:
+
+```php
+$container->get(\Yiisoft\Di\Reference\TagReference::id('car'));
+```
+
+The result is an array that has two instances: `BlueCarService` and `RedCarService`.
+
+### Using tagged services in configuration
+
+Use `TagReference` to get tagged services in configuration:
+
+```php
+[
+    Garage::class => [
+        '__construct()' => [
+            \Yiisoft\Di\Reference\TagReference::to('car'),
+        ],    
+    ],
+],
+```
+
 ## Resetting services state
 
 Despite stateful services isn't a great practice, these are often inevitable. When you build long-running

src/Reference/TagReference.php

@@ -4,10 +4,13 @@
 
 namespace Yiisoft\Di\Reference;
 
+use InvalidArgumentException;
 use Yiisoft\Definitions\Reference;
 
+use function sprintf;
+
 /**
- * TagReference is a helper class used to specify a reference to a tag.
+ * Helper class 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
@@ -20,13 +23,18 @@ private function __construct()
 
     public static function to(string $tag): Reference
     {
-        return Reference::to(self::PREFIX . $tag);
+        return Reference::to(self::id($tag));
+    }
+
+    public static function id(string $tag): string
+    {
+        return 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));
+            throw new InvalidArgumentException(sprintf('Alias "%s" is not a tag alias.', $alias));
         }
         return substr($alias, 4);
     }

tests/Unit/Reference/TagReference/Resolve/A.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Di\Tests\Unit\Reference\TagReference\Resolve;
+
+final class A
+{
+}

tests/Unit/Reference/TagReference/Resolve/B.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Di\Tests\Unit\Reference\TagReference\Resolve;
+
+final class B
+{
+}

tests/Unit/Reference/TagReference/Resolve/Main.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Di\Tests\Unit\Reference\TagReference\Resolve;
+
+final class Main
+{
+    public array $data = [];
+}

tests/Unit/Reference/TagReference/Resolve/TagReferenceResolveTest.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Di\Tests\Unit\Reference\TagReference\Resolve;
+
+use PHPUnit\Framework\TestCase;
+use Yiisoft\Di\Container;
+use Yiisoft\Di\ContainerConfig;
+use Yiisoft\Di\Reference\TagReference;
+
+final class TagReferenceResolveTest extends TestCase
+{
+    public function testBase(): void
+    {
+        $container = new Container(
+            ContainerConfig::create()
+                ->withDefinitions([
+                    Main::class => [
+                        '$data' => TagReference::to('letters'),
+                    ],
+                ])
+                ->withTags([
+                    'letters' => [A::class, B::class],
+                ])
+        );
+
+        $main = $container->get(Main::class);
+
+        $this->assertCount(2, $main->data);
+        $this->assertInstanceOf(A::class, $main->data[0]);
+        $this->assertInstanceOf(B::class, $main->data[1]);
+    }
+}

tests/Unit/Reference/TagReferenceTest.php → tests/Unit/Reference/TagReference/TagReferenceTest.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Yiisoft\Di\Tests\Unit\Reference;
+namespace Yiisoft\Di\Tests\Unit\Reference\TagReference;
 
 use Error;
 use InvalidArgumentException;
@@ -69,4 +69,9 @@ public function has($id): bool
 
         $this->assertEquals('tag@test', $result);
     }
+
+    public function testId(): void
+    {
+        $this->assertSame('tag@test', TagReference::id('test'));
+    }
 }