PHP中动态类名访问的类实例类型提示与静态分析实践

$modelClass = '\App\Models\Book';

// 动态调用静态方法，例如Laravel Eloquent的each方法
$modelClass::each(function($instance) {
    // 此时，$instance 的具体类型在代码编写时并不直接可知
    echo $instance->title . PHP_EOL;
});

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Book extends Model
{
    protected $fillable = ['title', 'author'];
}

// 假设我们有一个通用的处理函数
/**
 * 处理给定模型类的所有实例，并打印其标题。
 *
 * @param class-string<\Illuminate\Database\Eloquent\Model> $modelClass  模型类的字符串名称
 * @return void
 */
function processModelTitles(string $modelClass): void
{
    // 对于Psalm等静态分析工具，我们可以使用结构化类型提示来描述匿名函数参数$instance的预期结构。
    // 这告诉Psalm，$instance 将是一个具有 'title' 属性（类型为string）的对象。
    $modelClass::each(
        /**
         * @param object{title:string} $instance
         */
        function($instance) {
            // 此时，静态分析工具会知道 $instance 具有 'title' 属性，并且是字符串类型
            echo $instance->title . PHP_EOL;

            // 如果尝试访问一个不存在的属性，例如 $instance->nonExistentProperty，
            // Psalm 将会发出警告，因为这不符合 object{title:string} 的定义。
            // echo $instance->nonExistentProperty; // Psalm would warn
        }
    );
}

// 调用示例
processModelTitles('\App\Models\Book');

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Book extends Model
{
    protected $fillable = ['title', 'author'];
    public function getAuthorName(): string { return $this->author; }
}

class Article extends Model
{
    protected $fillable = ['headline', 'content'];
    public function getHeadlineText(): string { return $this->headline; }
}

/**
 * @template T of \Illuminate\Database\Eloquent\Model  // 定义一个泛型T，它必须是Eloquent Model的子类
 * @param class-string<T> $modelClass  // $modelClass 是一个字符串，代表类型T的类名
 * @return void
 */
function processGenericModelInstances(string $modelClass): void
{
    $modelClass::each(
        /**
         * @param T $instance  // 此时，$instance 的类型被推断为泛型T，即传入的特定模型类
         */
        function($instance) {
            // 静态分析工具现在知道 $instance 是 T 类型，也就是传入的 $modelClass 所代表的类。
            // 这样就可以访问该类的特定属性和方法。
            echo "ID: " . $instance->id . PHP_EOL;

            if ($instance instanceof \App\Models\Book) {
                echo "Book Title: " . $instance->title . PHP_EOL;
                echo "Author: " . $instance->getAuthorName() . PHP_EOL; // 可以访问Book特有的方法
            } elseif ($instance instanceof \App\Models\Article) {
                echo "Article Headline: " . $instance->headline . PHP_EOL;
                echo "Headline Text: " . $instance->getHeadlineText() . PHP_EOL; // 可以访问Article特有的方法
            }
            // 对于共享属性，可以直接访问
            // echo $instance->created_at->format('Y-m-d') . PHP_EOL;
        }
    );
}

// 调用示例
processGenericModelInstances(\App\Models\Book::class);
processGenericModelInstances(\App\Models\Article::class);