在PHP开发中，我们经常会遇到根据配置、用户请求或数据库记录来动态决定使用哪一个类的情况。比如系统支持多种支付方式，类名可能是从数据库读出来的字符串，再通过new $className()来实例化。这种写法在运行期非常灵活，但给类型系统和静态分析工具带来了不小麻烦：工具并不知道$obj到底是什么类型，只能把它当作mixed，结果就是方法调用没有补全、潜在错误查不出来。
为什么动态类名会破坏类型提示
PHP是动态语言，变量$class在编译期没有任何约束。当我们写$instance = new $class();时，静态分析器如PHPStan、Psalm无法推断$class运行时的值，因此默认将$instance推导为object或mixed。这意味着后续调用$instance->pay()时，工具既不能确认pay方法存在，也无法校验参数类型。
更严重的是，如果动态类名字典来自不可信输入，而开发者又误以为工具能帮忙拦截拼错的类名，就可能在测试覆盖不到的分支里写出调用不存在方法的代码。只有理解静态分析器依赖的是“代码里写死的信息”，才能明白为什么必须主动提供类型线索。
基础方案：使用类字符串模板注解
PHPDoc提供了一种叫“类字符串（class-string）”的写法，可以告诉工具某个变量保存的是类名。进一步结合具体基类，能表达“这是某个子类的类名”。例如我们有一个抽象类Payment，各种支付渠道继承它：
<?php
abstract class Payment
{
abstract public function pay(float $amount): bool;
}
class Alipay extends Payment
{
public function pay(float $amount): bool
{
return true;
}
}
class WechatPay extends Payment
{
public function pay(float $amount): bool
{
return true;
}
}
/**
* @param class-string<Payment> $className
* @return Payment
*/
function makePayment(string $className): Payment
{
return new $className();
}
$name = 'Alipay';
$obj = makePayment($name);
$obj->pay(10.0);
在上面的代码里，@param class-string<Payment> $className明确说明传入的必须是代表Payment子类的字符串，而@return Payment让调用处拿到的是明确的父类类型。静态分析器就能确认$obj->pay()合法，并且如果某个类没继承Payment却被传入，工具会报错。
这种写法改动小、兼容性高，适合大部分简单工厂场景。不过它要求调用方传入的字符串确实是子类名，如果字符串来自外部，仍需要在运行期用is_subclass_of校验。
进阶实践：自定义断言与泛型
当动态类名来自数组映射或配置时，可以用断言函数把“字符串”收窄为“具体类实例”。Psalm和PHPStan都支持自定义断言注解，让工具在断言成功后自动更新类型。下面示例展示一个带校验的工厂：
<?php
/**
* @param class-string $class
* @param array<string,mixed> $config
* @return object
* @throws InvalidArgumentException
*/
function build(string $class, array $config): object
{
if (!class_exists($class)) {
throw new InvalidArgumentException('class not found: ' . $class);
}
$instance = new $class();
if (method_exists($instance, 'init')) {
$instance->init($config);
}
return $instance;
}
/**
* @template T of object
* @param class-string<T> $class
* @return T
*/
function buildTyped(string $class)
{
/** @var T $obj */
$obj = new $class();
return $obj;
}
$user = buildTyped('UserRepository');
$user->find(1);
这里@template T of object配合class-string<T>构成泛型约束：调用buildTyped('UserRepository')时，分析器会把返回类型识别为UserRepository而不是泛化的object。这样仓库类的方法都能被准确提示。
如果项目使用PHP 8.0以上，还可以用is_a配合assert让运行期和静态期双重保障。值得注意的是，静态分析无法执行运行期逻辑，所以任何动态分支里的类型收窄都要通过注解显式表达，不能指望工具猜出来。
静态分析工具配置建议
为了让动态类名相关规则生效，需要在PHPStan的配置文件里开启适当级别。一般建议业务项目用level 6以上，并单独为工厂文件加忽略或增强注解：
parameters:
level: 6
paths:
- src
ignoreErrors:
- '#Unsafe usage of new dynamic class#'
上面的配置表示全局严格检查，但允许动态实例化报出警告而不阻断CI，团队可以逐步补全注解。Psalm用户则可利用psalm-plugin编写自定义钩子，在扫描到new $var时自动要求对应的@param class-string存在。
配合编辑器如PHPStorm，开启PHPStan外部工具后，保存文件即可看到动态类处的类型波浪线。长期坚持注解动态类名，能显著降低重构时改错方法名的风险。
总结与取舍
动态类名访问在插件系统、策略模式中不可避免。完全禁止会损失扩展能力，完全放任则让静态分析失效。合理做法是：对外层输入做运行期校验，对内层工厂用class-string和泛型注解暴露类型，并让CI里的静态分析工具强制检查。如此既享受PHP的灵活，又拥有接近静态语言的安全网。
实践中建议把动态实例化收敛到少数工厂函数，而不是散落在业务代码各处。这样只需在工厂边界写好类型提示，业务层就能获得干净的对象实例与完整的IDE支持。