Add the PropertyRead and PropertyWrite attributes

Author: carlos-granados

README.md

@@ -92,12 +92,14 @@ And then install any needed extensions/plugins for the tools that you use.
 
 These are the available attributes and their corresponding PHPDoc annotations:
 
-| Attribute                       | PHPDoc Annotations |
-|---------------------------------|--------------------|
-| [IsReadOnly](doc/IsReadOnly.md) | `@readonly`        |
-| [Param](doc/Param.md)           | `@param`           |
-| [Property](doc/Property.md)     | `@property` `@var` |
-| [Returns](doc/Returns.md)       | `@return`          |
-| [Template](doc/Template.md)     | `@template`        |
-| [Type](doc/Type.md)             | `@var` `@return`   |
+| Attribute                             | PHPDoc Annotations |
+|---------------------------------------|--------------------|
+| [IsReadOnly](doc/IsReadOnly.md)       | `@readonly`        |
+| [Param](doc/Param.md)                 | `@param`           |
+| [Property](doc/Property.md)           | `@property` `@var` |
+| [PropertyRead](doc/PropertyRead.md)   | `@property-read`   |
+| [PropertyWrite](doc/PropertyWrite.md) | `@property-write`  |
+| [Returns](doc/Returns.md)             | `@return`          |
+| [Template](doc/Template.md)           | `@template`        |
+| [Type](doc/Type.md)                   | `@var` `@return`   |
 

doc/PropertyRead.md

@@ -0,0 +1,34 @@
+# `PropertyRead` Attribute
+
+This attribute is the equivalent of the `@property-read` annotation and is used to specify the type of properties accessed through magic `__get` methods. These properties can only be read and not written to. It can also be used to override wrong property types from a parent class. 
+
+## Arguments
+
+The attribute accepts one or more strings which describe the type of the properties. The attribute itself does not have a knowledge of which types are valid and which are not and this will depend on the implementation for each particular tool.
+
+We expect that the attribute will be able to accept both basic types like `string` or `array` and more advanced types like `array<string>` or `Collection<int>`. We aim to accept all the types accepted by static analysis tools for the `@property` annotation.
+
+The arguments can be named arguments and the type is applied to the properties with the same name in the class.
+
+They can also be unnamed arguments with a string that contains both the type and the name of the property, but we recommend using named arguments.
+
+If the class has more than one property that we want to specify, the types for the different properties can either be declared as a list of strings for a single `PropertyRead` attribute or as a list of `PropertyRead` attributes (or even a combination of both, though we don't expect this to be actually used).
+
+## Example usage
+
+```php
+<?php
+
+use PhpStaticAnalysis\Attributes\PropertyRead;
+
+#[PropertyRead(name: 'string')]
+#[PropertyRead('int $age')]
+#[PropertyRead(
+    index1: 'string[]',
+    index2: 'string[]',
+)]
+class PropertyReadExample
+{
+    ...
+}
+```

doc/PropertyWrite.md

@@ -0,0 +1,34 @@
+# `PropertyWrite` Attribute
+
+This attribute is the equivalent of the `@property-write` annotation and is used to specify the type of properties accessed through magic `__get` methods. These properties can only be written to and not read. It can also be used to override wrong property types from a parent class. 
+
+## Arguments
+
+The attribute accepts one or more strings which describe the type of the properties. The attribute itself does not have a knowledge of which types are valid and which are not and this will depend on the implementation for each particular tool.
+
+We expect that the attribute will be able to accept both basic types like `string` or `array` and more advanced types like `array<string>` or `Collection<int>`. We aim to accept all the types accepted by static analysis tools for the `@property` annotation.
+
+The arguments can be named arguments and the type is applied to the properties with the same name in the class.
+
+They can also be unnamed arguments with a string that contains both the type and the name of the property, but we recommend using named arguments.
+
+If the class has more than one property that we want to specify, the types for the different properties can either be declared as a list of strings for a single `PropertyWrite` attribute or as a list of `PropertyWrite` attributes (or even a combination of both, though we don't expect this to be actually used).
+
+## Example usage
+
+```php
+<?php
+
+use PhpStaticAnalysis\Attributes\PropertyWrite;
+
+#[PropertyWrite(name: 'string')]
+#[PropertyWrite('int $age')]
+#[PropertyWrite(
+    index1: 'string[]',
+    index2: 'string[]',
+)]
+class PropertyWriteExample
+{
+    ...
+}
+```

src/PropertyRead.php

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

src/PropertyWrite.php

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

tests/PropertyReadTest.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\PropertyRead;
+use PHPUnit\Framework\TestCase;
+
+#[PropertyRead(name: 'string')]
+#[PropertyRead('int $age')]
+#[PropertyRead(
+    index1: 'string[]',
+    index2: 'string[]',
+)]
+class PropertyReadTest extends TestCase
+{
+    public function testClassProperties(): void
+    {
+        $reflection = new ReflectionClass($this);
+        $this->assertEquals([
+            0 => 'int $age',
+            'name' => 'string',
+            'index1' => 'string[]',
+            'index2' => 'string[]',
+        ], self::getPropertiesFromReflection($reflection));
+    }
+
+    public static function getPropertiesFromReflection(
+        ReflectionProperty | ReflectionClass $reflection
+    ): array {
+        $attributes = $reflection->getAttributes();
+        $properties = [];
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === PropertyRead::class) {
+                $attribute->newInstance();
+                $properties = array_merge($properties, $attribute->getArguments());
+            }
+        }
+
+        return $properties;
+    }
+}

tests/PropertyWriteTest.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\PropertyWrite;
+use PHPUnit\Framework\TestCase;
+
+#[PropertyWrite(name: 'string')]
+#[PropertyWrite('int $age')]
+#[PropertyWrite(
+    index1: 'string[]',
+    index2: 'string[]',
+)]
+class PropertyWriteTest extends TestCase
+{
+    public function testClassProperties(): void
+    {
+        $reflection = new ReflectionClass($this);
+        $this->assertEquals([
+            0 => 'int $age',
+            'name' => 'string',
+            'index1' => 'string[]',
+            'index2' => 'string[]',
+        ], self::getPropertiesFromReflection($reflection));
+    }
+
+    public static function getPropertiesFromReflection(
+        ReflectionProperty | ReflectionClass $reflection
+    ): array {
+        $attributes = $reflection->getAttributes();
+        $properties = [];
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === PropertyWrite::class) {
+                $attribute->newInstance();
+                $properties = array_merge($properties, $attribute->getArguments());
+            }
+        }
+
+        return $properties;
+    }
+}