Add Mixin attribute

Author: carlos-granados

README.md

@@ -98,6 +98,7 @@ These are the available attributes and their corresponding PHPDoc annotations:
 | [Internal](doc/Internal.md)                           | `@internal`               |
 | [IsReadOnly](doc/IsReadOnly.md)                       | `@readonly`               |
 | [Method](doc/Method.md)                               | `@method`                 |
+| [Mixin](doc/Mixin.md)                                 | `@mixin`                  |
 | [Param](doc/Param.md)                                 | `@param`                  |
 | [Property](doc/Property.md)                           | `@property` `@var`        |
 | [PropertyRead](doc/PropertyRead.md)                   | `@property-read`          |

doc/Method.md

@@ -10,7 +10,7 @@ We expect that the attribute will be able to accept all the signatures accepted
 
 The arguments need to be unnamed arguments.
 
-If the class has more than one method that we want to specify, the types for the different properties can either be declared as a list of strings for a single `Method` attribute or as a list of `Method` attributes (or even a combination of both, though we don't expect this to be actually used).
+If the class has more than one method that we want to specify, the signatures for the different functions can either be declared as a list of strings for a single `Method` attribute or as a list of `Method` attributes (or even a combination of both, though we don't expect this to be actually used).
 
 ## Example usage
 

doc/Mixin.md

@@ -0,0 +1,43 @@
+# `Mixin` Attribute
+
+This attribute is the equivalent of the `@mixin` annotation and is used to specify that the class will proxy the methods and properties of the referenced class. 
+
+## Arguments
+
+The attribute accepts one or more strings which describe the name of the referenced classes. The attribute itself does not have a knowledge of which signatures are valid and which are not and this will depend on the implementation for each particular tool.
+
+The arguments need to be unnamed arguments.
+
+If the class has more than one mixin that we want to specify, the names of the referenced classes can either be declared as a list of strings for a single `Mixin` attribute or as a list of `Mixin` attributes (or even a combination of both, though we don't expect this to be actually used).
+
+## Example usage
+
+```php
+<?php
+
+use PhpStaticAnalysis\Attributes\Mixin;
+
+class A
+{
+    public function doA(): void
+    {
+    }
+}
+
+ #[Mixin('A')]
+class B
+{
+    public function doB(): void
+    {
+    }
+
+    public function __call($name, $arguments)
+    {
+        (new A())->$name(...$arguments);
+    }
+}
+
+$b = new B();
+$b->doB();
+$b->doA(); // works
+```

src/Mixin.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStaticAnalysis\Attributes;
+
+use Attribute;
+
+#[Attribute(
+    Attribute::TARGET_CLASS |
+    Attribute::IS_REPEATABLE
+)]
+final class Mixin
+{
+    public function __construct(
+        string ...$params
+    ) {
+    }
+}

tests/MixinTest.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\Mixin;
+use PHPUnit\Framework\TestCase;
+
+class A
+{
+}
+
+class B
+{
+}
+
+class C
+{
+}
+
+#[Mixin('A')]
+#[Mixin(
+    'B',
+    'C',
+)]
+class MixinTest extends TestCase
+{
+    public function testClassMixins(): void
+    {
+        $reflection = new ReflectionClass($this);
+        $this->assertEquals(['A', 'B', 'C'], self::getMixinsFromReflection($reflection));
+    }
+
+    public static function getMixinsFromReflection(
+        ReflectionClass $reflection
+    ): array {
+        $attributes = $reflection->getAttributes();
+        $mixins = [];
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === Mixin::class) {
+                $attribute->newInstance();
+                $mixins = array_merge($mixins, $attribute->getArguments());
+            }
+        }
+
+        return $mixins;
+    }
+}