Feature/Add support for PHP 8.4 and typing hint enhancement. (#26)

othercodes · web-flow · commit d5b2742f6317 · 2025-02-08T16:10:05.000+01:00
diff --git a/.gitattributes b/.gitattributes
@@ -3,4 +3,7 @@
 /phpunit.xml                export-ignore
 /tests                      export-ignore
 /README.md                  export-ignore
-sonar-project.properties    export-ignore
+/sonar-project.properties   export-ignore
+/phpstan.neon               export-ignore
+test.xml                    export-ignore
+/wiki                       export-ignore
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        php-version: [ '8.2', '8.3' ]
+        php-version: [ '8.2', '8.3', '8.4']
 
     steps:
       - name: Checkout source code
diff --git a/composer.json b/composer.json
@@ -19,7 +19,7 @@
     "mockery/mockery": "^1.6.0",
     "pestphp/pest": "^2.0",
     "pestphp/pest-plugin-faker": "^2.0",
-    "phpstan/phpstan": "^1.0",
+    "phpstan/phpstan": "^1.12",
     "phpstan/extension-installer": "^1.3",
     "phpstan/phpstan-mockery": "^1.1"
   },
@@ -36,11 +36,7 @@
   "scripts": {
     "test": "vendor/bin/pest --configuration=phpunit.xml --coverage-clover=coverage.xml --log-junit=test.xml",
     "test-cov": "vendor/bin/pest --configuration=phpunit.xml --coverage-html=coverage",
-    "analyse": "vendor/bin/phpstan analyse src tests --no-progress --level=8",
-    "check": [
-      "@analyse",
-      "@test"
-    ]
+    "analyse": "vendor/bin/phpstan analyse --no-progress"
   },
   "config": {
     "allow-plugins": {
diff --git a/phpstan.neon b/phpstan.neon
@@ -0,0 +1,5 @@
+parameters:
+    paths:
+        - src/
+        - tests/
+    level: 9
diff --git a/src/Criteria.php b/src/Criteria.php
@@ -179,7 +179,7 @@ public function withPageOffset(int $offset): self
         );
     }
 
-    public function withPageNumber(int $number, int $size = null): self
+    public function withPageNumber(int $number, ?int $size = null): self
     {
         return self::create(
             groups: $this->groups,
diff --git a/src/Errors/CriteriaError.php b/src/Errors/CriteriaError.php
@@ -28,8 +28,12 @@ class CriteriaError extends Error
      * @param  Throwable|null  $previous
      * @param  array<string>  $violations
      */
-    public function __construct(string $message = "", int $code = 0, Throwable $previous = null, array $violations = [])
-    {
+    public function __construct(
+        string $message = "",
+        int $code = 0,
+        ?Throwable $previous = null,
+        array $violations = []
+    ) {
         parent::__construct($message, $code, $previous);
 
         $this->violations = $violations;
@@ -42,7 +46,7 @@ public function __construct(string $message = "", int $code = 0, Throwable $prev
      * @param  Throwable|null  $previous
      * @return self
      */
-    public static function create(string $message, array $violations, int $code = 0, Throwable $previous = null): self
+    public static function create(string $message, array $violations, int $code = 0, ?Throwable $previous = null): self
     {
         return new self($message, $code, $previous, $violations);
     }
diff --git a/src/Filter.php b/src/Filter.php
@@ -22,12 +22,12 @@ final class Filter implements ValueObject
      *
      * @param  string  $field
      * @param  Operator  $operator
-     * @param  mixed  $value
+     * @param  scalar|null|array<scalar>  $value
      */
     public function __construct(
         private readonly string $field,
         private readonly Operator $operator,
-        private readonly mixed $value,
+        private readonly bool|float|int|string|null|array $value,
     ) {
         $this->check();
     }
@@ -37,10 +37,10 @@ public function __construct(
      *
      * @param  string  $field
      * @param  Operator  $operator
-     * @param  mixed  $value
+     * @param  scalar|null|array<scalar>  $value
      * @return Filter
      */
-    public static function create(string $field, Operator $operator, mixed $value): self
+    public static function create(string $field, Operator $operator, bool|float|int|string|null|array $value): self
     {
         return new self($field, $operator, $value);
     }
@@ -67,62 +67,122 @@ public static function fromArray(array $filter): self
             );
     }
 
-    public static function equal(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
+    public static function equal(string $field, bool|float|int|string|null $value): self
     {
         return self::create($field, Operator::EQUAL, $value);
     }
 
-    public static function notEqual(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
+    public static function notEqual(string $field, bool|float|int|string|null $value): self
     {
         return self::create($field, Operator::NOT_EQUAL, $value);
     }
 
-    public static function greaterThan(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
+    public static function greaterThan(string $field, bool|float|int|string|null $value): self
     {
         return self::create($field, Operator::GT, $value);
     }
 
-    public static function greaterOrEqualThan(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
+    public static function greaterOrEqualThan(string $field, bool|float|int|string|null $value): self
     {
         return self::create($field, Operator::GTE, $value);
     }
 
-    public static function lessThan(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
+    public static function lessThan(string $field, bool|float|int|string|null $value): self
     {
         return self::create($field, Operator::LT, $value);
     }
 
-    public static function lessOrEqualThan(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
+    public static function lessOrEqualThan(string $field, bool|float|int|string|null $value): self
     {
         return self::create($field, Operator::LTE, $value);
     }
 
-    public static function in(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  array<scalar>  $value
+     * @return self
+     */
+    public static function in(string $field, array $value): self
     {
         return self::create($field, Operator::IN, $value);
     }
 
-    public static function notIn(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  array<scalar>  $value
+     * @return self
+     */
+    public static function notIn(string $field, array $value): self
     {
         return self::create($field, Operator::NOT_IN, $value);
     }
 
-    public static function like(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
+    public static function like(string $field, bool|float|int|string|null $value): self
     {
         return self::create($field, Operator::LIKE, $value);
     }
 
-    public static function notLike(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
+    public static function notLike(string $field, bool|float|int|string|null $value): self
     {
         return self::create($field, Operator::NOT_LIKE, $value);
     }
 
-    public static function contains(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
+    public static function contains(string $field, bool|float|int|string|null $value): self
     {
         return self::create($field, Operator::CONTAINS, $value);
     }
 
-    public static function notContains(string $field, mixed $value): self
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
+    public static function notContains(string $field, bool|float|int|string|null $value): self
     {
         return self::create($field, Operator::NOT_CONTAINS, $value);
     }
@@ -150,9 +210,9 @@ public function operator(): Operator
     /**
      * Return the field value.
      *
-     * @return mixed
+     * @return scalar|null|array<scalar>
      */
-    public function value(): mixed
+    public function value(): bool|float|int|string|null|array
     {
         return $this->value;
     }
diff --git a/src/FilterGroup.php b/src/FilterGroup.php
@@ -69,31 +69,61 @@ public function addFilter(Filter $new): self
         return $this;
     }
 
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
     public function addFilterEqual(string $field, mixed $value): self
     {
         return $this->addFilter(Filter::equal($field, $value));
     }
 
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
     public function addFilterNotEqual(string $field, mixed $value): self
     {
         return $this->addFilter(Filter::notEqual($field, $value));
     }
 
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
     public function addFilterGreaterThan(string $field, mixed $value): self
     {
         return $this->addFilter(Filter::greaterThan($field, $value));
     }
 
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
     public function addFilterGreaterOrEqualThan(string $field, mixed $value): self
     {
         return $this->addFilter(Filter::greaterOrEqualThan($field, $value));
     }
 
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
     public function addFilterLessThan(string $field, mixed $value): self
     {
         return $this->addFilter(Filter::lessThan($field, $value));
     }
 
+    /**
+     * @param  string  $field
+     * @param  bool|float|int|string|null  $value
+     * @return self
+     */
     public function addFilterLessOrEqualThan(string $field, mixed $value): self
     {
         return $this->addFilter(Filter::lessOrEqualThan($field, $value));
@@ -119,21 +149,41 @@ public function addFilterNotIn(string $field, array $value): self
         return $this->addFilter(Filter::notIn($field, $value));
     }
 
+    /**
+     * @param  string  $field
+     * @param  string  $value
+     * @return self
+     */
     public function addFilterLike(string $field, string $value): self
     {
         return $this->addFilter(Filter::like($field, $value));
     }
 
+    /**
+     * @param  string  $field
+     * @param  string  $value
+     * @return self
+     */
     public function addFilterNotLike(string $field, string $value): self
     {
         return $this->addFilter(Filter::notLike($field, $value));
     }
 
+    /**
+     * @param  string  $field
+     * @param  string  $value
+     * @return self
+     */
     public function addFilterContains(string $field, string $value): self
     {
         return $this->addFilter(Filter::contains($field, $value));
     }
 
+    /**
+     * @param  string  $field
+     * @param  string  $value
+     * @return self
+     */
     public function addFilterNotContains(string $field, string $value): self
     {
         return $this->addFilter(Filter::notContains($field, $value));

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +parameters:
 +    paths:
 +        - src/
 +        - tests/
 +    level: 9
Original file line number	Diff line number	Diff line change
`@@ -179,7 +179,7 @@ public function withPageOffset(int $offset): self`
`179`	`179`	`);`
`180`	`180`	`}`
`181`	`181`
`182`		`- public function withPageNumber(int $number, int $size = null): self`
	`182`	`+ public function withPageNumber(int $number, ?int $size = null): self`
`183`	`183`	`{`
`184`	`184`	`return self::create(`
`185`	`185`	`groups: $this->groups,`
Original file line number	Diff line number	Diff line change
`@@ -22,12 +22,12 @@ final class Filter implements ValueObject`
`22`	`22`	`*`
`23`	`23`	`* @param string $field`
`24`	`24`	`* @param Operator $operator`
`25`		`- * @param mixed $value`
	`25`	`+ * @param scalar\|null\|array<scalar> $value`
`26`	`26`	`*/`
`27`	`27`	`public function __construct(`
`28`	`28`	`private readonly string $field,`
`29`	`29`	`private readonly Operator $operator,`
`30`		`- private readonly mixed $value,`
	`30`	`+ private readonly bool\|float\|int\|string\|null\|array $value,`
`31`	`31`	`) {`
`32`	`32`	`$this->check();`
`33`	`33`	`}`
`@@ -37,10 +37,10 @@ public function __construct(`
`37`	`37`	`*`
`38`	`38`	`* @param string $field`
`39`	`39`	`* @param Operator $operator`
`40`		`- * @param mixed $value`
	`40`	`+ * @param scalar\|null\|array<scalar> $value`
`41`	`41`	`* @return Filter`
`42`	`42`	`*/`
`43`		`- public static function create(string $field, Operator $operator, mixed $value): self`
	`43`	`+ public static function create(string $field, Operator $operator, bool\|float\|int\|string\|null\|array $value): self`
`44`	`44`	`{`
`45`	`45`	`return new self($field, $operator, $value);`
`46`	`46`	`}`
`@@ -67,62 +67,122 @@ public static function fromArray(array $filter): self`
`67`	`67`	`);`
`68`	`68`	`}`
`69`	`69`
`70`		`- public static function equal(string $field, mixed $value): self`
	`70`	`+ /**`
	`71`	`+ * @param string $field`
	`72`	`+ * @param bool\|float\|int\|string\|null $value`
	`73`	`+ * @return self`
	`74`	`+ */`
	`75`	`+ public static function equal(string $field, bool\|float\|int\|string\|null $value): self`
`71`	`76`	`{`
`72`	`77`	`return self::create($field, Operator::EQUAL, $value);`
`73`	`78`	`}`
`74`	`79`
`75`		`- public static function notEqual(string $field, mixed $value): self`
	`80`	`+ /**`
	`81`	`+ * @param string $field`
	`82`	`+ * @param bool\|float\|int\|string\|null $value`
	`83`	`+ * @return self`
	`84`	`+ */`
	`85`	`+ public static function notEqual(string $field, bool\|float\|int\|string\|null $value): self`
`76`	`86`	`{`
`77`	`87`	`return self::create($field, Operator::NOT_EQUAL, $value);`
`78`	`88`	`}`
`79`	`89`
`80`		`- public static function greaterThan(string $field, mixed $value): self`
	`90`	`+ /**`
	`91`	`+ * @param string $field`
	`92`	`+ * @param bool\|float\|int\|string\|null $value`
	`93`	`+ * @return self`
	`94`	`+ */`
	`95`	`+ public static function greaterThan(string $field, bool\|float\|int\|string\|null $value): self`
`81`	`96`	`{`
`82`	`97`	`return self::create($field, Operator::GT, $value);`
`83`	`98`	`}`
`84`	`99`
`85`		`- public static function greaterOrEqualThan(string $field, mixed $value): self`
	`100`	`+ /**`
	`101`	`+ * @param string $field`
	`102`	`+ * @param bool\|float\|int\|string\|null $value`
	`103`	`+ * @return self`
	`104`	`+ */`
	`105`	`+ public static function greaterOrEqualThan(string $field, bool\|float\|int\|string\|null $value): self`
`86`	`106`	`{`
`87`	`107`	`return self::create($field, Operator::GTE, $value);`
`88`	`108`	`}`
`89`	`109`
`90`		`- public static function lessThan(string $field, mixed $value): self`
	`110`	`+ /**`
	`111`	`+ * @param string $field`
	`112`	`+ * @param bool\|float\|int\|string\|null $value`
	`113`	`+ * @return self`
	`114`	`+ */`
	`115`	`+ public static function lessThan(string $field, bool\|float\|int\|string\|null $value): self`
`91`	`116`	`{`
`92`	`117`	`return self::create($field, Operator::LT, $value);`
`93`	`118`	`}`
`94`	`119`
`95`		`- public static function lessOrEqualThan(string $field, mixed $value): self`
	`120`	`+ /**`
	`121`	`+ * @param string $field`
	`122`	`+ * @param bool\|float\|int\|string\|null $value`
	`123`	`+ * @return self`
	`124`	`+ */`
	`125`	`+ public static function lessOrEqualThan(string $field, bool\|float\|int\|string\|null $value): self`
`96`	`126`	`{`
`97`	`127`	`return self::create($field, Operator::LTE, $value);`
`98`	`128`	`}`
`99`	`129`
`100`		`- public static function in(string $field, mixed $value): self`
	`130`	`+ /**`
	`131`	`+ * @param string $field`
	`132`	`+ * @param array<scalar> $value`
	`133`	`+ * @return self`
	`134`	`+ */`
	`135`	`+ public static function in(string $field, array $value): self`
`101`	`136`	`{`
`102`	`137`	`return self::create($field, Operator::IN, $value);`
`103`	`138`	`}`
`104`	`139`
`105`		`- public static function notIn(string $field, mixed $value): self`
	`140`	`+ /**`
	`141`	`+ * @param string $field`
	`142`	`+ * @param array<scalar> $value`
	`143`	`+ * @return self`
	`144`	`+ */`
	`145`	`+ public static function notIn(string $field, array $value): self`
`106`	`146`	`{`
`107`	`147`	`return self::create($field, Operator::NOT_IN, $value);`
`108`	`148`	`}`
`109`	`149`
`110`		`- public static function like(string $field, mixed $value): self`
	`150`	`+ /**`
	`151`	`+ * @param string $field`
	`152`	`+ * @param bool\|float\|int\|string\|null $value`
	`153`	`+ * @return self`
	`154`	`+ */`
	`155`	`+ public static function like(string $field, bool\|float\|int\|string\|null $value): self`
`111`	`156`	`{`
`112`	`157`	`return self::create($field, Operator::LIKE, $value);`
`113`	`158`	`}`
`114`	`159`
`115`		`- public static function notLike(string $field, mixed $value): self`
	`160`	`+ /**`
	`161`	`+ * @param string $field`
	`162`	`+ * @param bool\|float\|int\|string\|null $value`
	`163`	`+ * @return self`
	`164`	`+ */`
	`165`	`+ public static function notLike(string $field, bool\|float\|int\|string\|null $value): self`
`116`	`166`	`{`
`117`	`167`	`return self::create($field, Operator::NOT_LIKE, $value);`
`118`	`168`	`}`
`119`	`169`
`120`		`- public static function contains(string $field, mixed $value): self`
	`170`	`+ /**`
	`171`	`+ * @param string $field`
	`172`	`+ * @param bool\|float\|int\|string\|null $value`
	`173`	`+ * @return self`
	`174`	`+ */`
	`175`	`+ public static function contains(string $field, bool\|float\|int\|string\|null $value): self`
`121`	`176`	`{`
`122`	`177`	`return self::create($field, Operator::CONTAINS, $value);`
`123`	`178`	`}`
`124`	`179`
`125`		`- public static function notContains(string $field, mixed $value): self`
	`180`	`+ /**`
	`181`	`+ * @param string $field`
	`182`	`+ * @param bool\|float\|int\|string\|null $value`
	`183`	`+ * @return self`
	`184`	`+ */`
	`185`	`+ public static function notContains(string $field, bool\|float\|int\|string\|null $value): self`
`126`	`186`	`{`
`127`	`187`	`return self::create($field, Operator::NOT_CONTAINS, $value);`
`128`	`188`	`}`
`@@ -150,9 +210,9 @@ public function operator(): Operator`
`150`	`210`	`/**`
`151`	`211`	`* Return the field value.`
`152`	`212`	`*`
`153`		`- * @return mixed`
	`213`	`+ * @return scalar\|null\|array<scalar>`
`154`	`214`	`*/`
`155`		`- public function value(): mixed`
	`215`	`+ public function value(): bool\|float\|int\|string\|null\|array`
`156`	`216`	`{`
`157`	`217`	`return $this->value;`
`158`	`218`	`}`
Original file line number	Diff line number	Diff line change
`@@ -69,31 +69,61 @@ public function addFilter(Filter $new): self`
`69`	`69`	`return $this;`
`70`	`70`	`}`
`71`	`71`
	`72`	`+ /**`
	`73`	`+ * @param string $field`
	`74`	`+ * @param bool\|float\|int\|string\|null $value`
	`75`	`+ * @return self`
	`76`	`+ */`
`72`	`77`	`public function addFilterEqual(string $field, mixed $value): self`
`73`	`78`	`{`
`74`	`79`	`return $this->addFilter(Filter::equal($field, $value));`
`75`	`80`	`}`
`76`	`81`
	`82`	`+ /**`
	`83`	`+ * @param string $field`
	`84`	`+ * @param bool\|float\|int\|string\|null $value`
	`85`	`+ * @return self`
	`86`	`+ */`
`77`	`87`	`public function addFilterNotEqual(string $field, mixed $value): self`
`78`	`88`	`{`
`79`	`89`	`return $this->addFilter(Filter::notEqual($field, $value));`
`80`	`90`	`}`
`81`	`91`
	`92`	`+ /**`
	`93`	`+ * @param string $field`
	`94`	`+ * @param bool\|float\|int\|string\|null $value`
	`95`	`+ * @return self`
	`96`	`+ */`
`82`	`97`	`public function addFilterGreaterThan(string $field, mixed $value): self`
`83`	`98`	`{`
`84`	`99`	`return $this->addFilter(Filter::greaterThan($field, $value));`
`85`	`100`	`}`
`86`	`101`
	`102`	`+ /**`
	`103`	`+ * @param string $field`
	`104`	`+ * @param bool\|float\|int\|string\|null $value`
	`105`	`+ * @return self`
	`106`	`+ */`
`87`	`107`	`public function addFilterGreaterOrEqualThan(string $field, mixed $value): self`
`88`	`108`	`{`
`89`	`109`	`return $this->addFilter(Filter::greaterOrEqualThan($field, $value));`
`90`	`110`	`}`
`91`	`111`
	`112`	`+ /**`
	`113`	`+ * @param string $field`
	`114`	`+ * @param bool\|float\|int\|string\|null $value`
	`115`	`+ * @return self`
	`116`	`+ */`
`92`	`117`	`public function addFilterLessThan(string $field, mixed $value): self`
`93`	`118`	`{`
`94`	`119`	`return $this->addFilter(Filter::lessThan($field, $value));`
`95`	`120`	`}`
`96`	`121`
	`122`	`+ /**`
	`123`	`+ * @param string $field`
	`124`	`+ * @param bool\|float\|int\|string\|null $value`
	`125`	`+ * @return self`
	`126`	`+ */`
`97`	`127`	`public function addFilterLessOrEqualThan(string $field, mixed $value): self`
`98`	`128`	`{`
`99`	`129`	`return $this->addFilter(Filter::lessOrEqualThan($field, $value));`
`@@ -119,21 +149,41 @@ public function addFilterNotIn(string $field, array $value): self`
`119`	`149`	`return $this->addFilter(Filter::notIn($field, $value));`
`120`	`150`	`}`
`121`	`151`
	`152`	`+ /**`
	`153`	`+ * @param string $field`
	`154`	`+ * @param string $value`
	`155`	`+ * @return self`
	`156`	`+ */`
`122`	`157`	`public function addFilterLike(string $field, string $value): self`
`123`	`158`	`{`
`124`	`159`	`return $this->addFilter(Filter::like($field, $value));`
`125`	`160`	`}`
`126`	`161`
	`162`	`+ /**`
	`163`	`+ * @param string $field`
	`164`	`+ * @param string $value`
	`165`	`+ * @return self`
	`166`	`+ */`
`127`	`167`	`public function addFilterNotLike(string $field, string $value): self`
`128`	`168`	`{`
`129`	`169`	`return $this->addFilter(Filter::notLike($field, $value));`
`130`	`170`	`}`
`131`	`171`
	`172`	`+ /**`
	`173`	`+ * @param string $field`
	`174`	`+ * @param string $value`
	`175`	`+ * @return self`
	`176`	`+ */`
`132`	`177`	`public function addFilterContains(string $field, string $value): self`
`133`	`178`	`{`
`134`	`179`	`return $this->addFilter(Filter::contains($field, $value));`
`135`	`180`	`}`
`136`	`181`
	`182`	`+ /**`
	`183`	`+ * @param string $field`
	`184`	`+ * @param string $value`
	`185`	`+ * @return self`
	`186`	`+ */`
`137`	`187`	`public function addFilterNotContains(string $field, string $value): self`
`138`	`188`	`{`
`139`	`189`	`return $this->addFilter(Filter::notContains($field, $value));`