CakePHP 4、PhpStorm与PHPStan的对象类类型混淆问题求助

此前曾就「CakePHP Entity vs EntityInterface」相关问题提问但未跟进，现重新咨询。

我用PhpStorm开发基于CakePHP 4的应用，同时用PHPCS、PHPUnit和PHPStan做提交前检查，但目前遇到CakePHP、PhpStorm与PHPUnit之间对模型返回数据的类型识别混淆问题，具体如下：

业务代码片段 #

$user = $this->Orders->Users->get($user->getIdentifier());
$cart = $this->Orders->Carts
    ->find('complete')
    ->where(['id' => $cart_id])
    ->first();
$this->checkForItems($cart);

PhpStorm 类型提示报错 #

Expected parameter of type '\Visualize\Model\Entity\Cart', 'array|\Cake\Datasource\EntityInterface|null' provided

目标方法定义 #

/**
 * @param Cart $cart The current shopping cart
 *
 * @return void
 */
public function checkForItems(Cart $cart) {
    if (empty($cart->cart_lines)) {
        throw new InternalErrorException('There are no line items in this cart');
    }
}

核心疑问与痛点 #

我对$cart调用get_class()后发现，它实际是Visualize\Model\Entity\Order对象，但PHPUnit却无法识别这一实际类型。想问是不是缺少代码注释文档才导致这种类型混淆？

这种混淆严重拖慢开发效率：如果把参数声明为EntityInterface，PHPUnit识别不了数据库字段；如果声明为具体的Cart实体，又会出现类型不匹配的提示，我得反复调整类型定义才能正常开发。

内容的提问来源于stack exchange，提问作者Tom Belknap