PHP Laravel Eloquent未定义self静态方法调用原理及@method作用

开发过程中遇到未在类中显式定义却可正常执行的方法调用，核心调用语句如下：

self::whereIdenityNumber($identityNumber)->exists();

对应业务代码：

public static function generateUniqueIdentityNumber()
{
    $identityNumber = strtoupper(Str::random(10));
    while (true) {
        $isExist = self::whereIdenityNumber($identityNumber)->exists();
        if ($isExist) {
            self::generateUniqueIdenityNumber();
        }
        break;
    }

    return $identityNumber;
}

当前代码运行无异常，类的Docblock中存在如下@method声明：

* @method static \Illuminate\Database\Eloquent\Builder|\App\Models\IdentityUser whereIdentityNumber($value)

这类动态方法是Laravel Eloquent模型基于PHP魔术方法实现的特性：

• PHP提供了__callStatic魔术方法，当调用类中不存在的静态方法时，PHP不会直接抛出错误，会自动触发该类（或父类）中定义的__callStatic方法，将原始调用的方法名、参数列表传入做统一处理。
• Eloquent的基类Model中已经实现了这套逻辑，针对where[字段名]格式的调用，内部会解析where后缀的字符串，自动转化为对应数据库字段的等值查询：比如whereIdentityNumber($value)会被等价处理为where('identity_number', $value)，最终走常规查询构造器逻辑执行，所以不需要在模型中显式定义该方法也能正常运行。

注意：当前代码中方法名存在拼写笔误，whereIdenityNumber、generateUniqueIdenityNumber都漏写了Identity中的t字符，虽然动态查询按字段匹配暂不影响运行，但长期留存容易引发隐性bug。

Docblock中的@method声明不属于PHP原生的方法定义范畴，它是PHPDoc规范下的文档标注，不会被PHP引擎解析执行，仅用于向IDE、静态分析工具传递类型、方法存在性的提示信息。

Intelephense作为静态分析工具，识别类方法的来源包含三类：

• 代码中显式定义的类方法、继承自父类的方法、trait引入的方法
• 类中通过__call、__callStatic魔术方法声明支持的通用动态调用
• 类Docblock中通过@method显式标注的方法

你在注释中写的@method声明已经明确告知分析工具当前类存在whereIdentityNumber静态方法，因此Intelephense会将其视为合法调用，不会抛出未定义方法的错误。即使没有手动写该注释，配合Laravel IDE辅助文件生成工具，Intelephense也能自动解析模型对应的数据表字段，推导生成所有where[字段名]格式的动态方法提示，不会误报。

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