Add Pure and Impure attributes

Author: carlos-granados

Diff for: README.md

@@ -92,27 +92,29 @@ 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                  |
-|-------------------------------------------------------|-------------------------------------|
-| [Deprecated](doc/Deprecated.md)                       | `@deprecated`                       |
-| [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`                            |
-| [ParamOut](doc/ParamOut.md)                           | `@param-out`                        |
-| [Property](doc/Property.md)                           | `@property` `@var`                  |
-| [PropertyRead](doc/PropertyRead.md)                   | `@property-read`                    |
-| [PropertyWrite](doc/PropertyWrite.md)                 | `@property-write`                   |
-| [RequireExtends](doc/RequireExtends.md)               | `@require-extends`                  |
-| [RequireImplements](doc/RequireImplements.md)         | `@require-implements`               |
-| [Returns](doc/Returns.md)                             | `@return`                           |
-| [SelfOut](doc/SelfOut.md)                             | `@self-out` `@this-out`             |
-| [Template](doc/Template.md)                           | `@template`                         |
-| [TemplateContravariant](doc/TemplateContravariant.md) | `@template-contravariant`           |
-| [TemplateCovariant](doc/TemplateCovariant.md)         | `@template-covariant`               |
-| [TemplateExtends](doc/TemplateExtends.md)             | `@extends` `@template-extends`      |
-| [TemplateImplements](doc/TemplateImplements.md)       | `@implements` `@template-implements`|
-| [TemplateUse](doc/TemplateUse.md)                     | `@use` `@template-use`              |
-| [Type](doc/Type.md)                                   | `@var` `@return`                    |
+| Attribute                                             | PHPDoc Annotations                   |
+|-------------------------------------------------------|--------------------------------------|
+| [Deprecated](doc/Deprecated.md)                       | `@deprecated`                        |
+| [Impure](doc/Impure.md)                               | `@impure`                            |
+| [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`                             |
+| [ParamOut](doc/ParamOut.md)                           | `@param-out`                         |
+| [Property](doc/Property.md)                           | `@property` `@var`                   |
+| [PropertyRead](doc/PropertyRead.md)                   | `@property-read`                     |
+| [PropertyWrite](doc/PropertyWrite.md)                 | `@property-write`                    |
+| [Pure](doc/Pure.md)                                   | `@pure`                              |
+| [RequireExtends](doc/RequireExtends.md)               | `@require-extends`                   |
+| [RequireImplements](doc/RequireImplements.md)         | `@require-implements`                |
+| [Returns](doc/Returns.md)                             | `@return`                            |
+| [SelfOut](doc/SelfOut.md)                             | `@self-out` `@this-out`              |
+| [Template](doc/Template.md)                           | `@template`                          |
+| [TemplateContravariant](doc/TemplateContravariant.md) | `@template-contravariant`            |
+| [TemplateCovariant](doc/TemplateCovariant.md)         | `@template-covariant`                |
+| [TemplateExtends](doc/TemplateExtends.md)             | `@extends` `@template-extends`       |
+| [TemplateImplements](doc/TemplateImplements.md)       | `@implements` `@template-implements` |
+| [TemplateUse](doc/TemplateUse.md)                     | `@use` `@template-use`               |
+| [Type](doc/Type.md)                                   | `@var` `@return`                     |
 

Diff for: doc/Impure.md

@@ -0,0 +1,29 @@
+# `Impure` Attribute
+
+This attribute is the equivalent of the `@impure` annotation for class methods and functions.
+
+## Arguments
+
+The attribute accepts no arguments.
+
+## Example usage
+
+```php
+<?php
+
+use PhpStaticAnalysis\Attributes\Impure;
+
+class ImpureExample
+{
+    public static int $i = 0;
+    
+    #[Impure]
+    public static function addCumulative(int $left) : int
+    {
+        self::$i += $left;
+        return self::$i;
+    }
+    
+  ...
+}
+```

Diff for: doc/Pure.md

@@ -0,0 +1,26 @@
+# `Pure` Attribute
+
+This attribute is the equivalent of the `@pure` annotation for class methods and functions.
+
+## Arguments
+
+The attribute accepts no arguments.
+
+## Example usage
+
+```php
+<?php
+
+use PhpStaticAnalysis\Attributes\Pure;
+
+class PureExample
+{
+    #[Pure]
+    public static function add(int $left, int $right) : int 
+    {
+        return $left + $right;
+    }
+    
+  ...
+}
+```

Diff for: src/Impure.php

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

Diff for: src/Pure.php

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

Diff for: tests/ImpureTest.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\Impure;
+use PHPUnit\Framework\TestCase;
+
+class ImpureTest extends TestCase
+{
+    public function testImpureMethod(): void
+    {
+        $this->assertTrue($this->methodImpure());
+    }
+
+    public function testImpureFunction(): void
+    {
+        $this->assertTrue(functionImpure());
+    }
+
+    #[Impure]
+    private function methodImpure(): bool
+    {
+        return $this->getImpure(__FUNCTION__);
+    }
+
+    private function getImpure(string $methodName): bool
+    {
+        $reflection = new ReflectionMethod($this, $methodName);
+        return self::getImpureFromReflection($reflection);
+    }
+
+    public static function getImpureFromReflection(
+        ReflectionMethod | ReflectionFunction $reflection
+    ): bool {
+        $attributes = $reflection->getAttributes();
+        $impure = false;
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === Impure::class) {
+                $attribute->newInstance();
+                $impure = true;
+            }
+        }
+
+        return $impure;
+    }
+}
+
+#[Impure]
+function functionImpure(): bool
+{
+    $reflection = new ReflectionFunction(__FUNCTION__);
+    return ImpureTest::getImpureFromReflection($reflection);
+}

Diff for: tests/PureTest.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\Pure;
+use PHPUnit\Framework\TestCase;
+
+class PureTest extends TestCase
+{
+    public function testPureMethod(): void
+    {
+        $this->assertTrue($this->methodPure());
+    }
+
+    public function testPureFunction(): void
+    {
+        $this->assertTrue(functionPure());
+    }
+
+    #[Pure]
+    private function methodPure(): bool
+    {
+        return $this->getPure(__FUNCTION__);
+    }
+
+    private function getPure(string $methodName): bool
+    {
+        $reflection = new ReflectionMethod($this, $methodName);
+        return self::getPureFromReflection($reflection);
+    }
+
+    public static function getPureFromReflection(
+        ReflectionMethod | ReflectionFunction $reflection
+    ): bool {
+        $attributes = $reflection->getAttributes();
+        $pure = false;
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === Pure::class) {
+                $attribute->newInstance();
+                $pure = true;
+            }
+        }
+
+        return $pure;
+    }
+}
+
+#[Pure]
+function functionPure(): bool
+{
+    $reflection = new ReflectionFunction(__FUNCTION__);
+    return PureTest::getPureFromReflection($reflection);
+}