用途:在 PHP 中同时实现运行时校验与静态分析类型收窄。PHPDoc 为分析器收窄类型,Assert 断言在 PHP 类型系统无法保证处强制校验,两者互补。
安装:composer require webmozart/assert;PHPStan 用户另装 composer require --dev phpstan/phpstan-webmozart-assert,并在 phpstan.neon 中 includes: vendor/phpstan/phpstan-webmozart-assert/extension.neon(使用 extension-installer 则自动注册)。Psalm 无需插件,Assert 自带 @psalm-assert 注解。
主要能力:PHPDoc 标量与对象类型(non-empty-string、positive-int、class-string)、数组形状 array{id: int, name: string, email?: string}、泛型 array<string,int>、list<User>、non-empty-list、类型别名 @phpstan-type/@psalm-type 与 import-type、模板 @template。运行时用 Assert::range、isArray、keyExists、string、inArray、allStringNotEmpty、allNullOrInteger 等,配合 @var 强制断言。
工作流:先注解,再在方法入口等边界断言,避免冗余断言,多处复用的形状定义别名。
推断模式:仅通过 PHPDoc 与内部断言补充类型,绝不改动原生参数/返回类型或函数签名;保守注解,无法确定用 mixed,不猜测。
决策规则:PHP 已强制的类型不再断言;只在边界断言;用 Assert::isInstanceOf 代替强制转换;优先具体断言;可扩展结构用开放形状;推断模式下错误 PHPDoc 比缺失更糟。
限制:资料未提供具体版本要求、性能数据或收费信息。