Merge pull request #4 from DaveLiddament/feature/add-test-tag

Add #[TestTag]

Author: DaveLiddament

README.md

@@ -4,9 +4,10 @@ This library provides attributes for extending the PHP language (e.g. adding `pa
 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:**
-- [package](#package) 
-- [friend](#friend)
-- [sealed](#sealed)
+- [Friend](#friend)
+- [Package](#package) 
+- [Sealed](#sealed)
+- [TestTag](#testtag)
 
 
 ### Contents
@@ -15,9 +16,10 @@ The intention, at least initially, is that these extra language features are enf
   - [PHPStan](#phpstan)
   - [Psalm](#psalm)
 - [New Language Features](#new-language-features)
-  - [package](#package)
-  - [friend](#friend)
-  - [sealed](#sealed)
+  - [Package](#package)
+  - [Friend](#friend)
+  - [Sealed](#sealed)
+  - [TestTag](#testtag)
 - [Further examples](#further-examples)
 - [Contributing](#contributing)
 
@@ -148,7 +150,7 @@ namespace Bar {
 **NOTES:**
 
 - If adding the `#[Package]` to a method, this method MUST have public visibility. 
-- If a class is marked with `#[Package]` then all its public methods are treated as having protected visibility. 
+- If a class is marked with `#[Package]` then all its public methods are treated as having package visibility. 
 - This is currently limited to method calls (including `__construct`).  
 - Namespaces must match exactly. E.g. a package level method in `Foo\Bar` is only accessible from `Foo\Bar`. It is not accessible from `Foo` or `Foo\Bar\Baz`
 
@@ -229,6 +231,46 @@ class Failure extends 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 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/testTag/testTagOnConstructor.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace TestTagOnConstructor;
+
+
+use DaveLiddament\PhpLanguageExtensions\TestTag;
+
+class Person
+{
+    #[TestTag]
+    public function __construct()
+    {
+    }
+
+    public static function create(): Person
+    {
+        return new Person(); // ERROR
+    }
+
+    public static function createSelf(): self
+    {
+        return new self(); // ERROR
+    }
+}
+
+class AnotherClass
+{
+    public function buildPerson(): Person
+    {
+        return new Person(); // ERROR
+    }
+}

examples/testTag/testTagOnConstructorIgnoredInTestClass.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace TestTagOnConstructorIgnoredInTestClass;
+
+use DaveLiddament\PhpLanguageExtensions\TestTag;
+
+class Person
+{
+    #[TestTag]
+    public function __construct()
+    {
+    }
+}
+
+class PersonTest
+{
+    public function buildPerson(): Person
+    {
+        return new Person(); // OK TetTag called from a test class
+    }
+}

examples/testTag/testTagOnConstructorIgnoredInTestNamespace.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace TestTagOnConstructorIgnoredInTestNamespace {
+
+    use DaveLiddament\PhpLanguageExtensions\TestTag;
+
+    class Person
+    {
+        #[TestTag]
+        public function __construct()
+        {
+        }
+    }
+
+}
+
+
+namespace TestTagOnConstructorIgnoredInTestNamespace\Test {
+
+    use TestTagOnConstructorIgnoredInTestNamespace\Person;
+
+    class PersonBuilder
+    {
+        public function buildPerson(): Person
+        {
+            return new Person(); // OK TetTag called from the test namespace
+        }
+    }
+
+}

examples/testTag/testTagOnMethod.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TestTagOnMethod;
+
+use DaveLiddament\PhpLanguageExtensions\TestTag;
+
+class Person
+{
+    #[TestTag]
+    public function updateName(): void
+    {
+    }
+
+    public function update(): void
+    {
+        $this->updateName(); // ERROR
+    }
+}
+
+class Updater
+{
+    public function updater(Person $person): void
+    {
+        $person->updateName(); // ERROR
+    }
+}
+
+$person = new Person();
+$person->updateName(); // ERROR
+

examples/testTag/testTagOnMethodIgnoredInTestClass.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TestTagOnMethodIgnoredInTestClass;
+
+use DaveLiddament\PhpLanguageExtensions\TestTag;
+
+class Person
+{
+    #[TestTag]
+    public function updateName(): void
+    {
+    }
+
+}
+
+class PersonTest
+{
+    public function updater(Person $person): void
+    {
+        $person->updateName(); // OK - Called from Test class
+    }
+}
+
+

examples/testTag/testTagOnMethodIgnoredInTestNamespace.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TestTagOnMethodIgnoredInTestNamespace {
+
+    use DaveLiddament\PhpLanguageExtensions\TestTag;
+
+    class Person
+    {
+        #[TestTag]
+        public function updateName(): void
+        {
+        }
+
+    }
+}
+
+namespace TestTagOnMethodIgnoredInTestNamespace\Test {
+
+    use TestTagOnMethodIgnoredInTestNamespace\Person;
+
+    class PersonUpdater
+    {
+        public function updater(Person $person): void
+        {
+            $person->updateName(); // OK - Called from Test namespace
+        }
+    }
+}
+

examples/testTag/testTagOnStaticMethod.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace TestTagOnStaticMethod;
+
+
+use DaveLiddament\PhpLanguageExtensions\TestTag;
+
+class Person
+{
+    #[TestTag]
+    public static function updateName(): void
+    {
+    }
+
+    public static function update(): void
+    {
+        Person::updateName(); // ERROR
+    }
+
+    public static function updateSelf(): void
+    {
+        self::updateName(); // ERROR
+    }
+}
+
+class Updater
+{
+    public function updater(): void
+    {
+        Person::updateName(); // ERROR
+    }
+}
+
+Person::updateName(); // ERROR

examples/testTag/testTagOnStaticMethodIgnoredInTestClass.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace TestTagOnStaticMethodIgnoredInTestClass;
+
+
+use DaveLiddament\PhpLanguageExtensions\TestTag;
+
+class Person
+{
+    #[TestTag]
+    public static function updateName(): void
+    {
+    }
+}
+
+class PersonTest
+{
+    public function updater(): void
+    {
+        Person::updateName(); // OK - Called from a test class
+    }
+}

examples/testTag/testTagOnStaticMethodIgnoredInTestNamespace.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace TestTagOnStaticMethodIgnoredInTestNamepace {
+
+
+    use DaveLiddament\PhpLanguageExtensions\TestTag;
+
+    class Person
+    {
+        #[TestTag]
+        public static function updateName(): void
+        {
+        }
+    }
+}
+
+namespace TestTagOnStaticMethodIgnoredInTestNamepace\Test {
+
+    use TestTagOnStaticMethodIgnoredInTestNamepace\Person;
+
+    class PersonUpdater
+    {
+        public function updater(): void
+        {
+            Person::updateName(); // OK - Called from a test namespace
+        }
+    }
+}