Add virtual IsEntity/IsLoaded interfaces for phpstan

composer.json

@@ -49,7 +49,7 @@
         "ergebnis/phpunit-slow-test-detector": "^2.9",
         "friendsofphp/php-cs-fixer": "^3.0",
         "phpstan/extension-installer": "^1.1",
-        "phpstan/phpstan": "^1.6",
+        "phpstan/phpstan": "^1.10.6",
         "phpstan/phpstan-deprecation-rules": "^1.0",
         "phpstan/phpstan-strict-rules": "^1.3",
         "phpunit/phpunit": "^9.5.25 || ^10.0"

phpstan-ext.neon

@@ -0,0 +1,17 @@
+services:
+    -
+        factory: Atk4\Data\Model\Phpstan\RemoveVirtualInterfacesFromStaticReturnTypeDmrtExtension(Atk4\Data\Model, Atk4\Data\Model\Phpstan\PhpdocTypeInterface)
+        tags:
+            - phpstan.broker.dynamicMethodReturnTypeExtension
+    -
+        factory: Atk4\Data\Model\Phpstan\RemoveVirtualInterfacesFromStaticReturnTypeDmrtExtension(Atk4\Data\Model, Atk4\Data\Model\Phpstan\PhpdocTypeInterface)
+        tags:
+            - phpstan.broker.dynamicStaticMethodReturnTypeExtension
+    -
+        factory: Atk4\Data\Model\Phpstan\RemoveVirtualInterfacesFromStaticReturnTypeDmrtExtension(Atk4\Data\Model, Atk4\Data\Model\Phpstan\PhpdocTypeInterface)
+        tags:
+            - phpstan.typeSpecifier.methodTypeSpecifyingExtension
+    -
+        factory: Atk4\Data\Model\Phpstan\RemoveVirtualInterfacesFromStaticReturnTypeDmrtExtension(Atk4\Data\Model, Atk4\Data\Model\Phpstan\PhpdocTypeInterface)
+        tags:
+            - phpstan.typeSpecifier.staticMethodTypeSpecifyingExtension

phpstan.neon.dist

@@ -1,5 +1,7 @@
 includes:
     - phar://phpstan.phar/conf/bleedingEdge.neon
+    # remove once https://github.com/phpstan/extension-installer/issues/36 is fixed
+    - phpstan-ext.neon
 
 parameters:
     level: 6
@@ -44,6 +46,27 @@ parameters:
             path: '*'
             count: 24
 
+        -
+            message: '~^Creating new PHPStan\\Reflection\\Type\\UnionTypeMethodReflection is not covered by backward compatibility promise\. The class might change in a minor PHPStan version\.$~'
+            path: 'src/Model/Phpstan/RemoveVirtualInterfacesFromStaticReturnTypeDmrtExtension.php'
+            count: 1
+        -
+            message: '~^Calling PHPStan\\Reflection\\Type\\UnionTypeMethodReflection::getName\(\) is not covered by backward compatibility promise\. The method might change in a minor PHPStan version\.$~'
+            path: 'src/Model/Phpstan/RemoveVirtualInterfacesFromStaticReturnTypeDmrtExtension.php'
+            count: 1
+        -
+            message: '~^Creating new PHPStan\\Reflection\\Type\\CalledOnTypeUnresolvedMethodPrototypeReflection is not covered by backward compatibility promise\. The class might change in a minor PHPStan version\.$~'
+            path: 'src/Model/Phpstan/RemoveVirtualInterfacesFromStaticReturnTypeDmrtExtension.php'
+            count: 1
+        -
+            message: '~^Calling PHPStan\\Reflection\\Type\\CalledOnTypeUnresolvedMethodPrototypeReflection::getTransformedMethod\(\) is not covered by backward compatibility promise\. The method might change in a minor PHPStan version\.$~'
+            path: 'src/Model/Phpstan/RemoveVirtualInterfacesFromStaticReturnTypeDmrtExtension.php'
+            count: 1
+        -
+            message: '~^Parameter #1 \$methodReflection of method Atk4\\Data\\Model\\Phpstan\\RemoveVirtualInterfacesFromStaticReturnTypeDmrtExtension::unresolveMethodReflection\(\) expects PHPStan\\Reflection\\ResolvedMethodReflection, PHPStan\\Reflection\\MethodReflection given\.$~'
+            path: 'src/Model/Phpstan/RemoveVirtualInterfacesFromStaticReturnTypeDmrtExtension.php'
+            count: 1
+
         # TODO these rules are generated, this ignores should be fixed in the code
         # for src/Schema/TestCase.php
         - '~^Call to an undefined method Atk4\\Data\\Persistence::dsql\(\)\.$~'

src/Model.php

@@ -16,6 +16,8 @@
 use Atk4\Core\ReadableCaptionTrait;
 use Atk4\Data\Field\CallbackField;
 use Atk4\Data\Field\SqlExpressionField;
+use Atk4\Data\Model\Phpstan\IsEntity;
+use Atk4\Data\Model\Phpstan\IsLoaded;
 use Atk4\Data\Model\Scope\AbstractScope;
 use Atk4\Data\Model\Scope\RootScope;
 use Mvorisek\Atk4\Hintable\Data\HintableModelTrait;
@@ -25,7 +27,7 @@
  *                                                               If the value is null then the record is considered to be new.
  * @property array<string, Field|Reference|Model\Join> $elements
  *
- * @phpstan-implements \IteratorAggregate<static>
+ * @phpstan-implements \IteratorAggregate<static&IsLoaded>
  */
 class Model implements \IteratorAggregate
 {
@@ -348,6 +350,8 @@
 
     /**
      * @return static
+     *
+     * @phpstan-return static&IsEntity
      */
     public function createEntity(): self
     {
@@ -372,7 +376,7 @@
         $entity->data = [];
         $entity->dirty = [];
 
-        return $entity;
+        return $entity; // @phpstan-ignore-line
     }
 
     /**
@@ -1202,7 +1206,7 @@
      * @param ($fromTryLoad is true ? false : bool) $fromReload
      * @param mixed                                 $id
      *
-     * @return ($fromTryLoad is true ? static|null : static)
+     * @return ($fromTryLoad is true ? (static&IsLoaded)|null : static&IsLoaded)
      */
     private function _load(bool $fromReload, bool $fromTryLoad, $id)
     {
@@ -1217,15 +1221,15 @@
             if ($fromReload) {
                 $this->unload();
 
-                return $this;
+                return $this; // @phpstan-ignore-line
             }
 
             return null;
         } elseif (is_object($res)) {
-            $res = (static::class)::assertInstanceOf($res);
+            (static::class)::assertInstanceOf($res);
             $res->assertIsEntity();
 
-            return $res;
+            return $res; // @phpstan-ignore-line
         }
 
         $data = $this->getModel()->getPersistence()->{$fromTryLoad ? 'tryLoad' : 'load'}($this->getModel(), $this->remapIdLoadToPersistence($id));
@@ -1245,18 +1249,18 @@
             if ($fromReload) {
                 $this->unload();
 
-                return $this;
+                return $this; // @phpstan-ignore-line
             }
 
             return null;
         } elseif (is_object($res)) {
-            $res = (static::class)::assertInstanceOf($res);
+            (static::class)::assertInstanceOf($res);
             $res->assertIsEntity();
 
-            return $res;
+            return $res; // @phpstan-ignore-line
         }
 
-        return $this;
+        return $this; // @phpstan-ignore-line
     }
 
     /**
@@ -1265,6 +1269,8 @@
      * @param mixed $id
      *
      * @return static|null
+     *
+     * @phpstan-return (static&IsLoaded)|null
      */
     public function tryLoad($id)
     {
@@ -1279,6 +1285,8 @@
      * @param mixed $id
      *
      * @return static
+     *
+     * @phpstan-return static&IsLoaded
      */
     public function load($id)
     {
@@ -1291,6 +1299,8 @@
      * Try to load one record. Will throw if more than one record exists, but not if there is no record.
      *
      * @return static|null
+     *
+     * @phpstan-return (static&IsLoaded)|null
      */
     public function tryLoadOne()
     {
@@ -1301,6 +1311,8 @@
      * Load one record. Will throw if more than one record exists.
      *
      * @return static
+     *
+     * @phpstan-return static&IsLoaded
      */
     public function loadOne()
     {
@@ -1313,6 +1325,8 @@
      * If only one record should match, use checked "tryLoadOne" method.
      *
      * @return static|null
+     *
+     * @phpstan-return (static&IsLoaded)|null
      */
     public function tryLoadAny()
     {
@@ -1325,6 +1339,8 @@
      * If only one record should match, use checked "loadOne" method.
      *
      * @return static
+     *
+     * @phpstan-return static&IsLoaded
      */
     public function loadAny()
     {
@@ -1334,7 +1350,7 @@
     /**
      * Reload model by taking its current ID.
      *
-     * @return $this
+     * @return $this&IsLoaded
      */
     public function reload()
     {
@@ -1343,11 +1359,11 @@
         $this->unload();
 
         $res = $this->_load(true, false, $id);
         if ($res !== $this) {
             throw new Exception('Entity instance does not match');
         }
 
         return $this;
     }
 
     /**
@@ -1356,6 +1372,8 @@
      * record in the database.
      *
      * @return static
+     *
+     * @phpstan-return static&IsEntity
      */
     public function duplicate()
     {
@@ -1368,7 +1386,7 @@
         $duplicateDirtyRef = $data;
         $duplicate->setId(null);
 
-        return $duplicate;
+        return $duplicate; // @phpstan-ignore-line
     }
 
     /**
@@ -1455,7 +1473,7 @@
      * @param ($field is string|Persistence\Sql\Expressionable ? ($value is null ? mixed : string) : never)                                                                                   $operator
      * @param ($operator is string ? mixed : never)                                                                                                                                           $value
      *
-     * @return ($fromTryLoad is true ? static|null : static)
+     * @return ($fromTryLoad is true ? (static&IsLoaded)|null : static&IsLoaded)
      */
     private function _loadBy(bool $fromTryLoad, $field, $operator = null, $value = null)
     {
@@ -1482,6 +1500,8 @@
      * @param ($operator is string ? mixed : never)                                                                                                                                           $value
      *
      * @return static
+     *
+     * @phpstan-return static&IsLoaded
      */
     public function loadBy($field, $operator = null, $value = null)
     {
@@ -1496,6 +1516,8 @@
      * @param ($operator is string ? mixed : never)                                                                                                                                           $value
      *
      * @return static|null
+     *
+     * @phpstan-return (static&IsLoaded)|null
      */
     public function tryLoadBy($field, $operator = null, $value = null)
     {
@@ -1791,6 +1813,8 @@
      * as a next iterator value.
      *
      * @return \Traversable<static>
+     *
+     * @phpstan-return \Traversable<static&IsLoaded>
      */
     #[\Override]
     final public function getIterator(): \Traversable
@@ -1841,16 +1865,16 @@
                 if ($res === false) {
                     continue;
                 } elseif (is_object($res)) {
-                    $res = (static::class)::assertInstanceOf($res);
+                    (static::class)::assertInstanceOf($res);
                     $res->assertIsEntity();
                 } else {
                     $res = $entity;
                 }
 
                 if ($res->getModel()->idField) {
                     yield $res->getId() => $res;
                 } else {
                     yield $res;
                 }
             }
         } finally {

src/Model/EntityFieldPair.php

@@ -7,6 +7,7 @@
 use Atk4\Core\WarnDynamicPropertyTrait;
 use Atk4\Data\Field;
 use Atk4\Data\Model;
+use Atk4\Data\Model\Phpstan\IsEntity;
 
 /**
  * @template-covariant TModel of Model
@@ -16,13 +17,13 @@ class EntityFieldPair
 {
     use WarnDynamicPropertyTrait;
 
-    /** @var TModel */
+    /** @var TModel&IsEntity */
     private $entity;
     /** @var string */
     private $fieldName;
 
     /**
-     * @param TModel $entity
+     * @param TModel&IsEntity $entity
      */
     public function __construct(Model $entity, string $fieldName)
     {
@@ -41,7 +42,7 @@ public function getModel(): Model
     }
 
     /**
-     * @return TModel
+     * @return TModel&IsEntity
      */
     public function getEntity(): Model
     {

src/Model/Phpstan/IsEntity.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Atk4\Data\Model\Phpstan;
+
+interface IsEntity extends PhpdocTypeInterface
+{
+}

src/Model/Phpstan/IsLoaded.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Atk4\Data\Model\Phpstan;
+
+interface IsLoaded extends IsEntity
+{
+}

src/Model/Phpstan/PhpdocTypeInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Atk4\Data\Model\Phpstan;
+
+interface PhpdocTypeInterface
+{
+    /**
+     * @deprecated Interface for phpdoc type for Phpstan only
+     *
+     * @return never
+     */
+    public function neverImplement(): void;
+}