Improving the MethodMustReturnType to support unions (#7)

* Improving the MethodMustReturnType rule

* Fixing edge cases

* Add regex support for method return type validation

- Introduced new classes for testing regex patterns in method return types.
- Enhanced the MethodMustReturnTypeRule to support regex matching for expected return types.
- Updated documentation to reflect regex usage in return type rules.
- Added comprehensive tests for various valid and invalid cases involving regex patterns.

---------

Co-authored-by: Florian Krämer <[email protected]>

Author: floriankraemer

data/MethodMustReturnType/AnyOfTestClass.php

@@ -0,0 +1,13 @@
+<?php
+
+class AnyOfTestClass
+{
+    // Valid cases
+    public function validObject(): SomeObject { return new SomeObject(); }
+    public function validVoid(): void { return; }
+    
+    // Invalid cases
+    public function invalidType(): int { return 1; }
+}
+
+class SomeObject {} 

data/MethodMustReturnType/EntityRegexTestClass.php

@@ -0,0 +1,19 @@
+<?php
+
+class EntityRegexTestClass
+{
+    // Valid cases - these should match the regex pattern
+    public function getUser(): UserEntity { return new UserEntity(); }
+    public function getProduct(): ProductEntity { return new ProductEntity(); }
+    public function getOrder(): OrderEntity { return new OrderEntity(); }
+    public function getVoid(): void { return; }
+    
+    // Invalid cases - these should not match
+    public function getOther(): OtherClass { return new OtherClass(); }
+    public function getString(): string { return 'test'; }
+}
+
+class UserEntity {}
+class ProductEntity {}
+class OrderEntity {}
+class OtherClass {} 

data/MethodMustReturnType/FacadeTestClass.php

@@ -0,0 +1,10 @@
+<?php
+
+class Facade
+{
+    public function someMethod(): SomeObject { return new SomeObject(); }
+    public function anotherMethod(): void { return; }
+    public function invalidMethod(): int { return 1; }
+}
+
+class SomeObject {} 

data/MethodMustReturnType/RegexAllOfTestClass.php

@@ -0,0 +1,16 @@
+<?php
+
+class RegexAllOfTestClass
+{
+    // Valid cases for allOf with regex patterns
+    public function validUnionWithUser(): UserEntity|int { return new UserEntity(); }
+    public function validUnionWithProduct(): ProductEntity|string { return 'test'; }
+    
+    // Invalid cases
+    public function invalidUnionMissingUser(): OtherClass|int { return 1; }
+    public function invalidUnionMissingProduct(): UserEntity|OtherClass { return new UserEntity(); }
+}
+
+class UserEntity {}
+class ProductEntity {}
+class OtherClass {} 

data/MethodMustReturnType/RegexTestClass.php

@@ -0,0 +1,18 @@
+<?php
+
+class RegexTestClass
+{
+    // Valid cases for regex patterns
+    public function validUserEntity(): UserEntity { return new UserEntity(); }
+    public function validProductEntity(): ProductEntity { return new ProductEntity(); }
+    public function validVoid(): void { return; }
+    public function validInt(): int { return 1; }
+    
+    // Invalid cases
+    public function invalidOtherClass(): OtherClass { return new OtherClass(); }
+    public function invalidString(): string { return 'test'; }
+}
+
+class UserEntity {}
+class ProductEntity {}
+class OtherClass {} 

data/MethodMustReturnType/ReturnTypeTestClass.php

@@ -2,10 +2,15 @@
 
 class ReturnTypeTestClass
 {
-    public function mustReturnInt(): void {}
-    public function mustReturnNullableString(): string {}
-    public function mustReturnVoid(): int {}
-    public function mustReturnSpecificObject(): OtherObject {}
+    // Invalid cases (should trigger errors)
+    public function mustReturnInt(): void { return; }
+    public function mustReturnNullableString(): string { return 'test'; }
+    public function mustReturnVoid(): int { return 1; }
+    public function mustReturnVoidLegacy(): int { return 1; }
+    public function mustReturnSpecificObject(): OtherObject { return new OtherObject(); }
+    public function mustReturnOneOf(): float { return 1.0; }
+    public function mustReturnAllOf(): int { return 1; }
+    public function mustReturnOneOfNullable(): string { return 'test'; }
 }
 
 class SomeObject {}

data/MethodMustReturnType/UnionTypeTestClass.php

@@ -0,0 +1,17 @@
+<?php
+
+class UnionTypeTestClass
+{
+    // Test cases for oneOf functionality
+    public function validOneOfInt(): int { return 1; }
+    public function validOneOfString(): string { return 'test'; }
+    public function validOneOfBool(): bool { return true; }
+    
+    // Test cases for allOf functionality (simplified)
+    public function validAllOfInt(): int { return 1; }
+    public function validAllOfString(): string { return 'test'; }
+    
+    // Invalid cases
+    public function invalidOneOf(): float { return 1.0; }
+    public function invalidAllOf(): bool { return true; }
+} 

docs/Rules.md

@@ -7,6 +7,7 @@ Add them to your `phpstan.neon` configuration file under the section `services`.
 Ensures that the nesting level of `if` and `try-catch` statements does not exceed a specified limit.
 
 **Configuration Example:**
+
 ```neon
     -
         class: Phauthentic\PHPStanRules\CleanCode\ControlStructureNestingRule
@@ -21,6 +22,7 @@ Ensures that the nesting level of `if` and `try-catch` statements does not excee
 Checks that methods do not have more than a specified number of arguments.
 
 **Configuration Example:**
+
 ```neon
     -
         class: Phauthentic\PHPStanRules\CleanCode\TooManyArgumentsRule
@@ -35,6 +37,7 @@ Checks that methods do not have more than a specified number of arguments.
 Ensures that classes matching specified patterns are declared as `readonly`.
 
 **Configuration Example:**
+
 ```neon
     -
         class: Phauthentic\PHPStanRules\Architecture\ClassMustBeReadonlyRule
@@ -53,6 +56,7 @@ The constructor takes an array of namespace dependencies. The key is the namespa
 In the example below nothing from `App\Domain` can depend on anything from `App\Controller`.
 
 **Configuration Example:**
+
 ```neon
     -
         class: Phauthentic\PHPStanRules\Architecture\DependencyConstraintsRule
@@ -69,6 +73,7 @@ In the example below nothing from `App\Domain` can depend on anything from `App\
 Ensures that classes matching specified patterns are declared as `final`.
 
 **Configuration Example:**
+
 ```neon
     -
         class: Phauthentic\PHPStanRules\Architecture\ClassMustBeFinalRule
@@ -83,6 +88,7 @@ Ensures that classes matching specified patterns are declared as `final`.
 Ensures that classes inside namespaces matching a given regex must have names matching at least one of the provided patterns.
 
 **Configuration Example:**
+
 ```neon
     -
         class: Phauthentic\PHPStanRules\Architecture\ClassnameMustMatchPatternRule
@@ -104,6 +110,7 @@ Ensures that classes inside namespaces matching a given regex must have names ma
 Ensures that specific exception types are not caught in catch blocks. This is useful for preventing the catching of overly broad exception types like `Exception`, `Error`, or `Throwable`.
 
 **Configuration Example:**
+
 ```neon
     -
         class: Phauthentic\PHPStanRules\Architecture\CatchExceptionOfTypeNotAllowedRule
@@ -118,6 +125,7 @@ Ensures that specific exception types are not caught in catch blocks. This is us
 Ensures that methods returning boolean values follow a specific naming convention. By default, boolean methods should start with `is`, `has`, `can`, `should`, `was`, or `will`.
 
 **Configuration Example:**
+
 ```neon
     -
         class: Phauthentic\PHPStanRules\Architecture\MethodsReturningBoolMustFollowNamingConventionRule
@@ -132,6 +140,7 @@ Ensures that methods returning boolean values follow a specific naming conventio
 Ensures that methods matching a class and method name pattern have a specific signature, including parameter types, names, and count.
 
 **Configuration Example:**
+
 ```neon
     -
         class: Phauthentic\PHPStanRules\Architecture\MethodSignatureMustMatchRule
@@ -151,16 +160,18 @@ Ensures that methods matching a class and method name pattern have a specific si
         tags:
             - phpstan.rules.rule
 ```
+
 - `pattern`: Regex for `ClassName::methodName`.
 - `minParameters`/`maxParameters`: Minimum/maximum number of parameters.
 - `signature`: List of expected parameter types and (optionally) name patterns.
 - `visibilityScope`: Optional visibility scope (e.g., `public`, `protected`, `private`).
 
 ## Method Must Return Type Rule {#method-must-return-type-rule}
 
-Ensures that methods matching a class and method name pattern have a specific return type, nullability, or are void.
+Ensures that methods matching a class and method name pattern have a specific return type, nullability, or are void. Supports union types with "oneOf" and "allOf" configurations.
 
 **Configuration Example:**
+
 ```neon
     -
         class: Phauthentic\PHPStanRules\Architecture\MethodMustReturnTypeRule
@@ -182,13 +193,41 @@ Ensures that methods matching a class and method name pattern have a specific re
                     pattern: '/^MyClass::reset$/'
                     type: 'void'
                     nullable: false
-                    void: true
+                    void: false
+                    objectTypePattern: null
+                -
+                    pattern: '/^MyClass::getValue$/'
+                    nullable: false
+                    void: false
+                    oneOf: ['int', 'string', 'bool']
+                    objectTypePattern: null
+                -
+                    pattern: '/^MyClass::getUnionType$/'
+                    nullable: false
+                    void: false
+                    allOf: ['int', 'string']
+                    objectTypePattern: null
+                -
+                    pattern: '/^MyClass::getAnyType$/'
+                    anyOf: ['object', 'void']
+                    objectTypePattern: null
+                -
+                    pattern: '/^MyClass::getEntity$/'
+                    anyOf: ['regex:/^App\\Entity\\/', 'void']
                     objectTypePattern: null
         tags:
             - phpstan.rules.rule
 ```
+
 - `pattern`: Regex for `ClassName::methodName`.
-- `type`: Expected return type (`int`, `string`, `object`, etc.).
+- `type`: Expected return type (`int`, `string`, `object`, `void`, etc.). When using `oneOf` or `allOf`, this field is optional.
 - `nullable`: Whether the return type must be nullable.
-- `void`: Whether the method must return void.
+- `void`: Legacy field for void return types (use `type: 'void'` instead).
 - `objectTypePattern`: Regex for object return types (if `type` is `object`).
+- `oneOf`: Array of types where one must match (for union types).
+- `allOf`: Array of types where all must be present in the union type.
+- `anyOf`: Alias for `oneOf` - array of types where one must match.
+
+**Regex Support**: You can use regex patterns in `oneOf`, `allOf`, and `anyOf` arrays by prefixing them with `regex:`. For example:
+- `'regex:/^App\\Entity\\/'` - matches any class starting with "App\Entity\"
+- `'regex:/^UserEntity$/'` - matches exactly "UserEntity"