Fix #242: Document that rule handler should not be called directly (#256)

samdark · web-flow · commit 56773299b59e · 2022-07-17T11:50:37.000+03:00
diff --git a/README.md b/README.md
@@ -644,6 +644,8 @@ final class CompanyNameHandler implements Rule\RuleHandlerInterface
 }
 ```
 
+> Note: Do not call handler's `validate()` method directly. It must be used via Validator only. 
+
 ##### Resolving rule handler dependencies
 
 Basically, you can use `SimpleRuleHandlerResolver` to resolve rule handler.
diff --git a/src/Rule/RuleHandlerInterface.php b/src/Rule/RuleHandlerInterface.php
@@ -19,6 +19,8 @@ interface RuleHandlerInterface
      * @param object $rule Rule containing validation parameters.
      * @param ValidationContext|null $context Optional validation context.
      *
+     * @internal Should be never called directly. Use {@see ValidatorInterface}.
+     *
      * @return Result
      */
     public function validate(mixed $value, object $rule, ?ValidationContext $context = null): Result;
diff --git a/tests/Rule/AbstractRuleValidatorTest.php b/tests/Rule/AbstractRuleValidatorTest.php
@@ -59,10 +59,10 @@ public function testDifferentRule(): void
 
     protected function validate(mixed $value, object $config): Result
     {
-        $ruleValidator = $this->getValidator();
+        $ruleHandler = $this->getRuleHandler();
         $context = $this->getValidationContext();
 
-        return $ruleValidator->validate($value, $config, $context);
+        return $ruleHandler->validate($value, $config, $context);
     }
 
     protected function formatMessage(string $message, array $params): string
@@ -76,7 +76,7 @@ abstract public function passedValidationProvider(): array;
 
     abstract public function failedValidationProvider(): array;
 
-    abstract protected function getValidator(): RuleHandlerInterface;
+    abstract protected function getRuleHandler(): RuleHandlerInterface;
 
     protected function getValidationContext(): ValidationContext
     {
diff --git a/tests/Rule/AtLeastHandlerTest.php b/tests/Rule/AtLeastHandlerTest.php
@@ -53,7 +53,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new AtLeastHandler();
     }
diff --git a/tests/Rule/BooleanHandlerTest.php b/tests/Rule/BooleanHandlerTest.php
@@ -69,7 +69,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new BooleanHandler();
     }
diff --git a/tests/Rule/CallbackHandlerTest.php b/tests/Rule/CallbackHandlerTest.php
@@ -75,7 +75,7 @@ public function testThrowExceptionWithInvalidReturn(): void
         $this->validate(null, $rule);
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new CallbackHandler();
     }
diff --git a/tests/Rule/CompareToHandlerTest.php b/tests/Rule/CompareToHandlerTest.php
@@ -92,7 +92,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new CompareToHandler();
     }
diff --git a/tests/Rule/CompositeHandlerTest.php b/tests/Rule/CompositeHandlerTest.php
@@ -72,7 +72,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new CompositeHandler();
     }
diff --git a/tests/Rule/CountHandlerTest.php b/tests/Rule/CountHandlerTest.php
@@ -122,7 +122,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new CountHandler();
     }
diff --git a/tests/Rule/EachHandlerTest.php b/tests/Rule/EachHandlerTest.php
@@ -75,7 +75,7 @@ public function indexedByPathErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new EachHandler();
     }
diff --git a/tests/Rule/EmailHandlerTest.php b/tests/Rule/EmailHandlerTest.php
@@ -152,7 +152,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new EmailHandler();
     }
diff --git a/tests/Rule/GroupRuleHandlerTest.php b/tests/Rule/GroupRuleHandlerTest.php
@@ -49,7 +49,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new GroupRuleHandler();
     }
diff --git a/tests/Rule/HasLengthHandlerTest.php b/tests/Rule/HasLengthHandlerTest.php
@@ -85,7 +85,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): HasLengthHandler
+    protected function getRuleHandler(): HasLengthHandler
     {
         return new HasLengthHandler();
     }
diff --git a/tests/Rule/InRangeHandlerTest.php b/tests/Rule/InRangeHandlerTest.php
@@ -80,7 +80,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new InRangeHandler();
     }
diff --git a/tests/Rule/IpHandlerTest.php b/tests/Rule/IpHandlerTest.php
@@ -238,7 +238,7 @@ public function testInitException(): void
         $this->validate('', $rule);
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new IpHandler();
     }
diff --git a/tests/Rule/JsonHandlerTest.php b/tests/Rule/JsonHandlerTest.php
@@ -124,7 +124,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new JsonHandler();
     }
diff --git a/tests/Rule/NestedHandlerTest.php b/tests/Rule/NestedHandlerTest.php
@@ -214,7 +214,7 @@ public function indexedByPathErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new NestedHandler();
     }
diff --git a/tests/Rule/NumberHandlerTest.php b/tests/Rule/NumberHandlerTest.php
@@ -123,7 +123,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new NumberHandler();
     }
diff --git a/tests/Rule/RegexHandlerTest.php b/tests/Rule/RegexHandlerTest.php
@@ -59,7 +59,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new RegexHandler();
     }
diff --git a/tests/Rule/RequiredHandlerTest.php b/tests/Rule/RequiredHandlerTest.php
@@ -38,7 +38,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new RequiredHandler();
     }
diff --git a/tests/Rule/SubsetHandlerTest.php b/tests/Rule/SubsetHandlerTest.php
@@ -50,7 +50,7 @@ public function customErrorMessagesProvider(): array
         ];
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new SubsetHandler();
     }
diff --git a/tests/Rule/UrlHandlerTest.php b/tests/Rule/UrlHandlerTest.php
@@ -95,7 +95,7 @@ public function testEnableIdnException(): void
         new Url(enableIDN: true);
     }
 
-    protected function getValidator(): RuleHandlerInterface
+    protected function getRuleHandler(): RuleHandlerInterface
     {
         return new UrlHandler();
     }

Original file line number	Diff line number	Diff line change
`@@ -644,6 +644,8 @@ final class CompanyNameHandler implements Rule\RuleHandlerInterface`
`644`	`644`	`}`
`645`	`645`	```
`646`	`646`
	`647`	+> Note: Do not call handler's `validate()` method directly. It must be used via Validator only.
	`648`	`+`
`647`	`649`	`##### Resolving rule handler dependencies`
`648`	`650`
`649`	`651`	Basically, you can use `SimpleRuleHandlerResolver` to resolve rule handler.
Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,8 @@ interface RuleHandlerInterface`
`19`	`19`	`* @param object $rule Rule containing validation parameters.`
`20`	`20`	`* @param ValidationContext\|null $context Optional validation context.`
`21`	`21`	`*`
	`22`	`+ * @internal Should be never called directly. Use {@see ValidatorInterface}.`
	`23`	`+ *`
`22`	`24`	`* @return Result`
`23`	`25`	`*/`
`24`	`26`	`public function validate(mixed $value, object $rule, ?ValidationContext $context = null): Result;`
Original file line number	Diff line number	Diff line change
`@@ -59,10 +59,10 @@ public function testDifferentRule(): void`
`59`	`59`
`60`	`60`	`protected function validate(mixed $value, object $config): Result`
`61`	`61`	`{`
`62`		`- $ruleValidator = $this->getValidator();`
	`62`	`+ $ruleHandler = $this->getRuleHandler();`
`63`	`63`	`$context = $this->getValidationContext();`
`64`	`64`
`65`		`- return $ruleValidator->validate($value, $config, $context);`
	`65`	`+ return $ruleHandler->validate($value, $config, $context);`
`66`	`66`	`}`
`67`	`67`
`68`	`68`	`protected function formatMessage(string $message, array $params): string`
`@@ -76,7 +76,7 @@ abstract public function passedValidationProvider(): array;`
`76`	`76`
`77`	`77`	`abstract public function failedValidationProvider(): array;`
`78`	`78`
`79`		`- abstract protected function getValidator(): RuleHandlerInterface;`
	`79`	`+ abstract protected function getRuleHandler(): RuleHandlerInterface;`
`80`	`80`
`81`	`81`	`protected function getValidationContext(): ValidationContext`
`82`	`82`	`{`
Original file line number	Diff line number	Diff line change
`@@ -53,7 +53,7 @@ public function customErrorMessagesProvider(): array`
`53`	`53`	`];`
`54`	`54`	`}`
`55`	`55`
`56`		`- protected function getValidator(): RuleHandlerInterface`
	`56`	`+ protected function getRuleHandler(): RuleHandlerInterface`
`57`	`57`	`{`
`58`	`58`	`return new AtLeastHandler();`
`59`	`59`	`}`
Original file line number	Diff line number	Diff line change
`@@ -69,7 +69,7 @@ public function customErrorMessagesProvider(): array`
`69`	`69`	`];`
`70`	`70`	`}`
`71`	`71`
`72`		`- protected function getValidator(): RuleHandlerInterface`
	`72`	`+ protected function getRuleHandler(): RuleHandlerInterface`
`73`	`73`	`{`
`74`	`74`	`return new BooleanHandler();`
`75`	`75`	`}`
Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ public function testThrowExceptionWithInvalidReturn(): void`
`75`	`75`	`$this->validate(null, $rule);`
`76`	`76`	`}`
`77`	`77`
`78`		`- protected function getValidator(): RuleHandlerInterface`
	`78`	`+ protected function getRuleHandler(): RuleHandlerInterface`
`79`	`79`	`{`
`80`	`80`	`return new CallbackHandler();`
`81`	`81`	`}`
Original file line number	Diff line number	Diff line change
`@@ -92,7 +92,7 @@ public function customErrorMessagesProvider(): array`
`92`	`92`	`];`
`93`	`93`	`}`
`94`	`94`
`95`		`- protected function getValidator(): RuleHandlerInterface`
	`95`	`+ protected function getRuleHandler(): RuleHandlerInterface`
`96`	`96`	`{`
`97`	`97`	`return new CompareToHandler();`
`98`	`98`	`}`
Original file line number	Diff line number	Diff line change
`@@ -72,7 +72,7 @@ public function customErrorMessagesProvider(): array`
`72`	`72`	`];`
`73`	`73`	`}`
`74`	`74`
`75`		`- protected function getValidator(): RuleHandlerInterface`
	`75`	`+ protected function getRuleHandler(): RuleHandlerInterface`
`76`	`76`	`{`
`77`	`77`	`return new CompositeHandler();`
`78`	`78`	`}`
Original file line number	Diff line number	Diff line change
`@@ -122,7 +122,7 @@ public function customErrorMessagesProvider(): array`
`122`	`122`	`];`
`123`	`123`	`}`
`124`	`124`
`125`		`- protected function getValidator(): RuleHandlerInterface`
	`125`	`+ protected function getRuleHandler(): RuleHandlerInterface`
`126`	`126`	`{`
`127`	`127`	`return new CountHandler();`
`128`	`128`	`}`
Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ public function indexedByPathErrorMessagesProvider(): array`
`75`	`75`	`];`
`76`	`76`	`}`
`77`	`77`
`78`		`- protected function getValidator(): RuleHandlerInterface`
	`78`	`+ protected function getRuleHandler(): RuleHandlerInterface`
`79`	`79`	`{`
`80`	`80`	`return new EachHandler();`
`81`	`81`	`}`