Merge branch 'main' into TestTagOnClass

Author: DaveLiddament

README.md

@@ -15,9 +15,11 @@ 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)
+- [RestrictTraitTo](#restricttraitto)
 - [Sealed](#sealed)
 - [TestTag](#testtag)
 
@@ -29,9 +31,11 @@ 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)
+  - [RestrictTraitTo](#restricttraitto)
   - [Sealed](#sealed)
   - [TestTag](#testtag)
   - Deprecated
@@ -129,7 +133,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
 
@@ -382,6 +419,32 @@ NOTE:
 - If you are using PHP 8.3 then use the real `#[Override]` attribute.
 - This implementation doesn't consider traits. 
 
+## RestrictTraitTo
+
+This limits the use of a Trait to only be used by a specified class of a child of that class.
+
+E.g. this trait is limited to classes that are or extend `Controller`
+
+```php
+#[RestrictTraitTo(Controller::class)]
+trait ControllerHelpers {}
+```
+
+This would be allowed:
+```php
+class LoginController extends Controller {
+    use ControllerHelpers;
+}
+```
+
+But this would NOT be allowed:
+```php
+class Repository {
+    use ControllerHelpers;
+}
+```
+
+
 ## Sealed
 
 This is inspired by the rejected [sealed classes RFC](https://wiki.php.net/rfc/sealed_classes)

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
+}

examples/restrictTraitTo/restrictTraitTo.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace RestrictTraitTo;
+
+use DaveLiddament\PhpLanguageExtensions\RestrictTraitTo;
+
+trait UseAnywhere {}
+
+#[RestrictTraitTo(Interface1::class)]
+trait UseOnlyOnInterface1 {}
+
+#[RestrictTraitTo(AbstractClass1::class)]
+trait UseOnlyOnAbstractClass1 {}
+
+#[RestrictTraitTo(Class2::class)]
+trait UseOnlyOnClass2 {}
+
+
+interface Interface1 {}
+
+
+class AClass {
+    use UseAnywhere; // OK
+    use UseOnlyOnInterface1; // ERROR RestrictTraitTo\Interface1
+    use UseOnlyOnAbstractClass1; // ERROR RestrictTraitTo\AbstractClass1
+    use UseOnlyOnClass2; // ERROR RestrictTraitTo\Class2
+}
+
+
+class ImplementsInterface1 implements Interface1 {
+    use UseAnywhere; // OK
+    use UseOnlyOnInterface1; // OK
+    use UseOnlyOnAbstractClass1; // ERROR RestrictTraitTo\AbstractClass1
+    use UseOnlyOnClass2; // ERROR RestrictTraitTo\Class2
+}
+
+abstract class AbstractClass1
+{
+
+}
+
+class ExtendsAbstractClass1 extends AbstractClass1 {
+    use UseAnywhere; // OK
+    use UseOnlyOnInterface1; // ERROR RestrictTraitTo\Interface1
+    use UseOnlyOnAbstractClass1; // OK
+    use UseOnlyOnClass2; // ERROR RestrictTraitTo\Class2
+}
+
+class Class2 {
+    use UseAnywhere; // OK
+    use UseOnlyOnInterface1; // ERROR RestrictTraitTo\Interface1
+    use UseOnlyOnAbstractClass1; // ERROR RestrictTraitTo\AbstractClass1
+    use UseOnlyOnClass2; // 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
+{
+}

src/RestrictTraitTo.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DaveLiddament\PhpLanguageExtensions;
+
+/**
+ * Enforces that the trait can only be used on the specified class, or children of that class.
+ *
+ * E.g. this trait is limited to classes that are or extend `Controller`
+ *
+ * ```
+ * #[RestrictTraitTo(Controller::class)]
+ * trait ControllerHelpers {}
+ * ```
+ *
+ * This would be allowed:
+ * ```
+ * class LoginController extends Controller {
+ *     use ControllerHelpers;
+ * }
+ * ```
+ *
+ * But this would NOT be allowed:
+ * ```
+ * class Repository {
+ *     use ControllerHelpers;
+ * }
+ * ```
+ */
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final class RestrictTraitTo
+{
+    /** @param class-string $className */
+    public function __construct(
+        public string $className,
+    ) {
+    }
+}