Correct PHPStan findings in validator (#808)

This pull request includes several changes to the `JsonSchema` library,
focusing on adding type hints and improving code documentation. The most
important changes include removing certain entries from
`phpstan-baseline.neon`, adding type hints to methods in
`Validator.php`, and updating deprecation notices.

Improvements to type hints and code documentation:

*
[`src/JsonSchema/Validator.php`](diffhunk://#diff-41de454e04e08a0284513e682c94d3f01f9c4a2a6b2faa51b5868bdd0826e42eL44-R48):
Added type hints to the `validate`, `check`, and `coerce` methods,
specifying the return type as `int` and including detailed parameter
documentation.
[[1]](diffhunk://#diff-41de454e04e08a0284513e682c94d3f01f9c4a2a6b2faa51b5868bdd0826e42eL44-R48)
[[2]](diffhunk://#diff-41de454e04e08a0284513e682c94d3f01f9c4a2a6b2faa51b5868bdd0826e42eL85-R104)

Updates to `phpstan-baseline.neon`:

*
[`phpstan-baseline.neon`](diffhunk://#diff-995edee38ad4f8387e58ebd52c31bcc04c56cc2448d331b1cf5e0b35c57b9efaL903-L932):
Removed multiple entries related to the `JsonSchema\Validator` class,
which were previously indicating missing type hints. These entries are
no longer needed due to the added type hints in the code.

Author: DannyvdSluijs

phpstan-baseline.neon

@@ -900,33 +900,3 @@ parameters:
 			count: 1
 			path: src/JsonSchema/Uri/UriRetriever.php
 
-		-
-			message: "#^Method JsonSchema\\\\Validator\\:\\:check\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: src/JsonSchema/Validator.php
-
-		-
-			message: "#^Method JsonSchema\\\\Validator\\:\\:check\\(\\) has parameter \\$schema with no type specified\\.$#"
-			count: 1
-			path: src/JsonSchema/Validator.php
-
-		-
-			message: "#^Method JsonSchema\\\\Validator\\:\\:check\\(\\) has parameter \\$value with no type specified\\.$#"
-			count: 1
-			path: src/JsonSchema/Validator.php
-
-		-
-			message: "#^Method JsonSchema\\\\Validator\\:\\:coerce\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: src/JsonSchema/Validator.php
-
-		-
-			message: "#^Method JsonSchema\\\\Validator\\:\\:coerce\\(\\) has parameter \\$schema with no type specified\\.$#"
-			count: 1
-			path: src/JsonSchema/Validator.php
-
-		-
-			message: "#^Method JsonSchema\\\\Validator\\:\\:coerce\\(\\) has parameter \\$value with no type specified\\.$#"
-			count: 1
-			path: src/JsonSchema/Validator.php
-

src/JsonSchema/Validator.php

@@ -41,14 +41,11 @@ class Validator extends BaseConstraint
      *
      * @param mixed $value
      * @param mixed $schema
-     * @param int   $checkMode
-     *
-     * @return int
      *
      * @phpstan-param int-mask-of<Constraint::CHECK_MODE_*> $checkMode
      * @phpstan-return int-mask-of<Validator::ERROR_*>
      */
-    public function validate(&$value, $schema = null, $checkMode = null)
+    public function validate(&$value, $schema = null, ?int $checkMode = null): int
     {
         // reset errors prior to validation
         $this->reset();
@@ -82,19 +79,29 @@ public function validate(&$value, $schema = null, $checkMode = null)
     /**
      * Alias to validate(), to maintain backwards-compatibility with the previous API
      *
-     * @deprecated
+     * @deprecated since 6.0.0, use Validator::validate() instead, to be removed in 7.0
+     *
+     * @param mixed $value
+     * @param mixed $schema
+     *
+     * @phpstan-return int-mask-of<Validator::ERROR_*>
      */
-    public function check($value, $schema)
+    public function check($value, $schema): int
     {
         return $this->validate($value, $schema);
     }
 
     /**
      * Alias to validate(), to maintain backwards-compatibility with the previous API
      *
-     * @deprecated
+     * @deprecated since 6.0.0, use Validator::validate() instead, to be removed in 7.0
+     *
+     * @param mixed $value
+     * @param mixed $schema
+     *
+     * @phpstan-return int-mask-of<Validator::ERROR_*>
      */
-    public function coerce(&$value, $schema)
+    public function coerce(&$value, $schema): int
     {
         return $this->validate($value, $schema, Constraint::CHECK_MODE_COERCE_TYPES);
     }