Add Immutable attribute

Author: carlos-granados

Diff for: README.md

@@ -18,16 +18,6 @@ In particular, these repositories are:
 - [Psalm plugin](https://github.com/php-static-analysis/psalm-plugin)
 - [RectorPHP rules to migrate annotations to attributes](https://github.com/php-static-analysis/rector-rule)
 
-## PHPStorm
-A plugin that fully supports these attributes will need to be created. Until this is ready you can get partial support by installing PHPStan, our PHPStan extension and enabling PHPStan support in PHPStorm (as described [here](https://www.jetbrains.com/help/phpstorm/using-phpstan.html)). You will then be able to see errors and messages related to these attributes in your code.
-
-Alternatively install Psalm, our Psalm extension and enable Psalm support in PHPStorm (as described [here](https://www.jetbrains.com/help/phpstorm/using-psalm.html))
-
-## VS Code Support
-An extension that fully supports these attributes will need to be created. Until this is ready you can get partial support by installing PHPStan, our PHPStan extension and a VS Code extension that supports PHPStan (for example [this one](https://github.com/SanderRonde/phpstan-vscode)). When you enable the extension you will be able to see errors and messages related to these attributes in your code.
-
-Alternatively install Psalm, our Psalm extension and a VS Code extension that supports Psam (for example [this one](https://github.com/psalm/psalm-vscode-plugin)) 
-
 ## Example
 
 In order to show how code would look with these attributes, we can look at the following example. This is how a class looks like with the current annotations:
@@ -95,6 +85,7 @@ These are the available attributes and their corresponding PHPDoc annotations:
 | Attribute                                             | PHPDoc Annotations                   |
 |-------------------------------------------------------|--------------------------------------|
 | [Deprecated](doc/Deprecated.md)                       | `@deprecated`                        |
+| [Immutable](doc/Immutable.md)                         | `@immutable`                         |
 | [Impure](doc/Impure.md)                               | `@impure`                            |
 | [Internal](doc/Internal.md)                           | `@internal`                          |
 | [IsReadOnly](doc/IsReadOnly.md)                       | `@readonly`                          |
@@ -119,3 +110,13 @@ These are the available attributes and their corresponding PHPDoc annotations:
 | [Throws](doc/Throws.md)                               | `@throws`                            |
 | [Type](doc/Type.md)                                   | `@var` `@return`                     |
 
+## PHPStorm Support
+A plugin that fully supports these attributes will need to be created. Until this is ready you can get partial support by installing PHPStan, our PHPStan extension and enabling PHPStan support in PHPStorm (as described [here](https://www.jetbrains.com/help/phpstorm/using-phpstan.html)). You will then be able to see errors and messages related to these attributes in your code.
+
+Alternatively install Psalm, our Psalm extension and enable Psalm support in PHPStorm (as described [here](https://www.jetbrains.com/help/phpstorm/using-psalm.html))
+
+## VS Code Support
+An extension that fully supports these attributes will need to be created. Until this is ready you can get partial support by installing PHPStan, our PHPStan extension and a VS Code extension that supports PHPStan (for example [this one](https://github.com/SanderRonde/phpstan-vscode)). When you enable the extension you will be able to see errors and messages related to these attributes in your code.
+
+Alternatively install Psalm, our Psalm extension and a VS Code extension that supports Psam (for example [this one](https://github.com/psalm/psalm-vscode-plugin)) 
+

Diff for: doc/Immutable.md

@@ -0,0 +1,21 @@
+# `Immutable` Attribute
+
+This attribute is the equivalent of the `@immutable` annotation for classes, traits and interfaces.
+
+## Arguments
+
+The attribute accepts no arguments.
+
+## Example usage
+
+```php
+<?php
+
+use PhpStaticAnalysis\Attributes\Immutable;
+
+#[Immutable] // All properties are readonly
+class ImmutableExample
+{
+    ...
+}
+```

Diff for: src/Immutable.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStaticAnalysis\Attributes;
+
+use Attribute;
+
+#[Attribute(
+    Attribute::TARGET_CLASS
+)]
+final class Immutable
+{
+    public function __construct()
+    {
+    }
+}

Diff for: tests/ImmutableTest.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\Immutable;
+use PHPUnit\Framework\TestCase;
+
+#[Immutable]
+class ImmutableTest extends TestCase
+{
+    public function testClassImmutable(): void
+    {
+        $reflection = new ReflectionClass($this);
+        $this->assertTrue(self::getImmutableFromReflection($reflection));
+    }
+
+    public function testTraitImmutable(): void
+    {
+        $reflection = new ReflectionClass(ImmutableTestTrait::class);
+        $this->assertTrue(self::getImmutableFromReflection($reflection));
+    }
+
+    public function testInterfaceImmutable(): void
+    {
+        $reflection = new ReflectionClass(ImmutableTestInterface::class);
+        $this->assertTrue(self::getImmutableFromReflection($reflection));
+    }
+
+    public static function getImmutableFromReflection(
+        ReflectionClass $reflection
+    ): bool {
+        $attributes = $reflection->getAttributes();
+        $immutable = false;
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === Immutable::class) {
+                $attribute->newInstance();
+                $immutable = true;
+            }
+        }
+
+        return $immutable;
+    }
+}
+
+#[Immutable]
+trait ImmutableTestTrait
+{
+}
+
+#[Immutable]
+interface ImmutableTestInterface
+{
+}