Merge pull request #15 from DaveLiddament/feature/tidy-up

Tidy up

Author: DaveLiddament

README.md

@@ -10,8 +10,7 @@
 [![PHPStan level 8](https://img.shields.io/badge/PHPStan-max%20level-brightgreen.svg)](https://github.com/DaveLiddament/php-language-extensions/blob/main/phpstan.neon)
 
 
-
-This library provides attributes for extending the PHP language (e.g. adding `package` visibility).
+This library provides [attributes](https://www.php.net/manual/en/language.attributes.overview.php) that are used by static analysers to enforce new language features. 
 The intention, at least initially, is that these extra language features are enforced by static analysis tools (such as Psalm, PHPStan and, ideally, PhpStorm) and NOT at runtime.
 
 **Language feature added:**
@@ -51,7 +50,7 @@ Use one of these:
 
 ### PHPStan
 
-To use PHPStan to enforce package level visibility add [this extension](https://github.com/DaveLiddament/phpstan-php-language-extensions). 
+If you're using PHPStan then use [this extension](https://github.com/DaveLiddament/phpstan-php-language-extensions) to enforce the rules.
 
 ```shell
 composer require --dev dave-liddament/phpstan-php-language-extensions
@@ -330,7 +329,7 @@ class PersonValidator {
 }
 ```
 
-By default, only constructor arguments are checked. Most DI should be done via constructor injection. 
+By default, only constructor arguments are checked. Most DI should be done via constructor injection.
 
 In cases where dependencies are injected by methods that aren't constructors, the method must be marked with a `#[CheckInjectableVersion]`:
 
@@ -353,6 +352,70 @@ class MyService
 
 
 
+
+## Sealed
+
+This is inspired by the rejected [sealed classes RFC](https://wiki.php.net/rfc/sealed_classes)
+
+The `#[Sealed]` attribute takes a list of classes or interfaces that can extend/implement the class/interface.
+
+E.g.
+
+```php
+
+#[Sealed([Success::class, Failure::class])]
+abstract class Result {} // Result can only be extended by Success or Failure
+
+// OK
+class Success extends Result {}
+
+// OK
+class Failure extends Result {}
+
+// ERROR AnotherClass is not allowed to extend Result
+class AnotherClass extends Result {}
+```
+
+
+## TestTag
+
+The `#[TestTag]` attribute is an idea borrowed from hardware testing. Methods marked with this attribute are only available to test code.
+
+E.g.
+
+```php
+class Person {
+
+    #[TestTag]
+    public function setId(int $id) 
+    {
+      $this->id = $id;
+    }
+}
+
+
+function updatePersonId(Person $person): void 
+{
+    $person->setId(10);  // ERROR - not test code.
+}
+
+
+class PersonTest 
+{
+    public function setup(): void
+    {
+        $person = new Person();
+        $person->setId(10); // OK - This is test code.
+    }
+}
+```
+
+NOTES:
+- Methods with the`#[TestTag]` MUST have public visibility.
+- For determining what is "test code" see the relevant plugin. E.g. the [PHPStan extension](https://github.com/DaveLiddament/phpstan-php-language-extensions) can be setup to either:
+    - Assume all classes that end `Test` is test code. See [className config option](https://github.com/DaveLiddament/phpstan-php-language-extensions#exclude-checks-on-class-names-ending-with-test).
+    - Assume all classes within a given namespace is test code. See [namespace config option](https://github.com/DaveLiddament/phpstan-php-language-extensions#exclude-checks-based-on-test-namespace).
+
 ## Further examples
 
 More detailed examples of how to use attributes is found in [examples](examples/).

examples/sealed/sealedClasses.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SealedClasses;
+
+use DaveLiddament\PhpLanguageExtensions\Sealed;
+
+class Success extends Response // OK
+{
+}
+
+class Failed extends Response // OK
+{
+}
+
+#[Sealed(Success::class, Failed::class)]
+class Response
+{
+}
+
+
+class AnotherClass extends Response // ERROR AnotherClass can not extend Response
+{
+}

examples/sealed/sealedInterfaces.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SealedInterfaces;
+
+use DaveLiddament\PhpLanguageExtensions\Sealed;
+
+class Success implements Response // OK
+{
+}
+
+class Failed implements Response // OK
+{
+}
+
+#[Sealed(Success::class, Failed::class)]
+interface Response
+{
+}
+
+
+class AnotherClass implements Response // ERROR AnotherClass can not implement Response
+{
+}

phpstan.neon

@@ -4,4 +4,4 @@ parameters:
     - src
 
     ignoreErrors:
-    - '#^Constructor of class DaveLiddament\\PhpLanguageExtensions\\[a-zA-Z]+ has an unused parameter \$[a-z]+\.$#'
+    - '#^Constructor of class DaveLiddament\\PhpLanguageExtensions\\[a-zA-Z]+ has an unused parameter \$[a-zA-Z]+\.$#'

src/CheckInjectableVersion.php

@@ -5,6 +5,6 @@
 namespace DaveLiddament\PhpLanguageExtensions;
 
 #[\Attribute(\Attribute::TARGET_METHOD)]
-class CheckInjectableVersion
+final class CheckInjectableVersion
 {
 }

src/Friend.php

@@ -8,7 +8,7 @@
  * Limits calling methods to those listed as the method's or class's friends.
  */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD)]
-class Friend
+final class Friend
 {
     /** @param class-string ...$friends */
     public function __construct(

src/InjectableVersion.php

@@ -5,6 +5,6 @@
 namespace DaveLiddament\PhpLanguageExtensions;
 
 #[\Attribute(\Attribute::TARGET_CLASS)]
-class InjectableVersion
+final class InjectableVersion
 {
 }

src/Package.php

@@ -8,6 +8,6 @@
  * Limit calls to classes or methods with the Package attribute to calls from classes in the name namespace.
  */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD)]
-class Package
+final class Package
 {
 }

src/Sealed.php

@@ -8,7 +8,7 @@
  * Limits the classes that can extend/implement to those listed in $permitted.
  */
 #[\Attribute(\Attribute::TARGET_CLASS)]
-class Sealed
+final class Sealed
 {
     /** @param class-string ...$permitted */
     public function __construct(

src/TestTag.php

@@ -6,8 +6,9 @@
 
 /**
  * Add the TestTag attribute to a method that should only be called by test code.
+ * Attempts to call from non-test code will raise an issue.
  */
 #[\Attribute(\Attribute::TARGET_METHOD)]
-class TestTag
+final class TestTag
 {
 }