Merge pull request #31 from DaveLiddament/feature/must-use-result

ADD #[MustUseResult] attribute

Author: DaveLiddament

README.md

@@ -15,6 +15,7 @@ The intention, at least initially, is that these extra language features are enf
 
 **Language feature added:**
 - [Friend](#friend)
+- [MustUseResult](#mustuseresult)
 - [NamespaceVisibility](#namespaceVisibility)
 - [InjectableVersion](#injectableVersion)
 - [Override](#override)
@@ -29,6 +30,7 @@ The intention, at least initially, is that these extra language features are enf
   - [Psalm](#psalm)
 - [New Language Features](#new-language-features)
   - [Friend](#friend)
+  - [MustUseResult](#mustuseresult)
   - [NamespaceVisibility](#namespaceVisibility)
   - [InjectableVersion](#injectableVersion)
   - [Override](#override)
@@ -129,7 +131,40 @@ $person = new Person();
   ```  
 - This is currently limited to method calls (including `__construct`).
 
+## MustUseResult
 
+Add #[MustUseResult] attribute that can be used on methods. This enforces the result from the method call must be used.
+
+E.g. if you have a class like this:
+
+```php
+
+class Money {
+
+  public function __construct(public readonly int $pence)
+  {}
+  
+  #[MustUseResult]
+  public function add(int $pence): self
+  {
+     return new self($pence + $this->pence);
+  }
+}
+```
+
+You might misuse the `add` method in this way:
+
+```php
+$cost = new Money(5);
+$cost->add(6); // ERROR - This statement has no effect. 
+```
+
+But this would be OK:
+
+```php
+$cost = new Money(5);
+$updatedCost = $cost->add(6); // OK - The return from add method is being used.
+```
 
 ## NamespaceVisibility
 

examples/mustUseResult/mustUseResultOnMethod.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace MustUseResultOnMethod {
+
+
+    use DaveLiddament\PhpLanguageExtensions\MustUseResult;
+
+    class AClass {
+
+        #[MustUseResult]
+        public function mustUseResult(): int
+        {
+            return 1;
+        }
+
+        public function dontNeedToUseResult(): int
+        {
+            return 2;
+        }
+
+    }
+
+
+    $class = new AClass();
+
+    $class->dontNeedToUseResult(); // OK
+
+    $class->mustUseResult(); // ERROR
+
+    echo $class->mustUseResult(); // OK;
+
+    $value = 1 + $class->mustUseResult(); // OK
+}

examples/mustUseResult/mustUseResultOnStaticMethod.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace MustUseResultOnMethod {
+
+
+    use DaveLiddament\PhpLanguageExtensions\MustUseResult;
+
+    class AClass {
+
+        #[MustUseResult]
+        public static function mustUseResult(): int
+        {
+            return 1;
+        }
+
+        public static function dontNeedToUseResult(): int
+        {
+            return 2;
+        }
+
+    }
+
+
+    AClass::dontNeedToUseResult(); // OK
+
+    AClass::mustUseResult(); // ERROR
+
+    echo AClass::mustUseResult(); // OK;
+
+    $value = 1 + AClass::mustUseResult(); // OK
+}

src/MustUseResult.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DaveLiddament\PhpLanguageExtensions;
+
+/**
+ * Enforces that the result from a method call must be used.
+ *
+ * Assume the following class:
+ * ```
+ * class Money {
+ *
+ *   public function __construct(public readonly int $pence)
+ *   {}
+ *
+ *   #[MustUseResult]
+ *   public function add(int $pence): self
+ *   {
+ *     return new self($pence + $this->pence);
+ *   }
+ * }
+ * ```
+ *
+ * You might misuse the `add` method in this way:
+ *
+ * ```
+ * $cost = new Money(5);
+ * $cost->add(6); // ERROR - This statement has no effect.
+ * ```
+ *
+ * But this would be OK:
+ *
+ * ```
+ * $cost = new Money(5);
+ * $updatedCost = $cost->add(6); // OK - The return from add method is being used.
+ * ```
+ */
+#[\Attribute(\Attribute::TARGET_METHOD)]
+final class MustUseResult
+{
+}