guard库非composer官方包，需手动配置psr-4自动加载；推荐封装requirestring等静态方法做参数校验，避免替代类型声明或滥用为中间件，并确保异常被框架正确捕获与日志记录。
Guard 库不是 Composer 官方包，得先确认来源
Composer 本身不托管 guard 这个包名——它既不是 PHP 官方组件，也不是主流生态（如 Symfony、Laravel）的内置校验库。直接运行 composer require guard 会报错：Could not find package guard in a version matching...。实际项目中常见的“Guard”类库，多数是开发者自建的工具类，或误指 symfony/security-guard（已废弃）、spatie/laravel-permission（权限控制）等周边方案。
如果你手头已有本地 Guard 类（比如一个 src/Security/Guard.php），它提供类似 Guard::requireNotNull($value, 'name') 的断言方法，那引入方式就不是靠 Composer 自动安装，而是：
- 确保该类遵循 PSR-4 自动加载规范（命名空间与路径匹配）
- 在
composer.json的"autoload"段声明对应映射，例如："autoload": { "psr-4": { "App\Security\": "src/Security/" } } - 运行
composer dump-autoload刷新自动加载器
用 assert() 或自定义 Guard 类做前置校验更可靠
PHP 原生 assert() 在开发环境有效，但生产环境默认关闭（zend.assertions = -1），不适合关键业务逻辑的健壮性保障。真正落地的前置条件校验，推荐封装成可复用的静态方法，比如：
class Guard
{
public static function requireString(mixed $value, string $paramName): string
{
if (!is_string($value)) {
throw new InvalidArgumentException(
sprintf('Parameter "%s" must be string, %s given', $paramName, gettype($value))
);
}
return $value;
}
public static function requireArrayNonEmpty(array $value, string $paramName): array
{
if (empty($value)) {
throw new InvalidArgumentException(sprintf('Parameter "%s" must be non-empty array', $paramName));
}
return $value;
}
}
这类方法调用简单、错误信息明确、不依赖外部扩展，且能被 IDE 正确识别类型提示。
别把 Guard 当中间件或全局拦截器用
有人试图把 Guard 方法塞进构造函数或控制器基类里统一校验，结果导致错误堆叠、调试困难。Guard 的定位是「参数契约」，不是「请求守门员」。正确用法是：
- 只在校验入口参数时调用，比如方法第一行：
Guard::requireString($name, 'name') - 每个方法各自负责自己的输入契约，不传递责任
- 避免在循环体内重复调用（性能损耗明显），应提前校验整个数组再进入循环
- 不要替代类型声明（PHP 8+ 的
string $name已覆盖基础类型检查）
生产环境注意 error_reporting 和异常捕获层级
Guard 抛出的 InvalidArgumentException 属于逻辑错误，不该被通用 try/catch 吞掉。实际部署时需确认：
- Web 框架是否已配置全局异常处理器来格式化这类异常（如 Laravel 的
Handler::render） -
error_reporting是否包含E_WARNING—— 有些 Guard 实现用trigger_error()，这在严格模式下会被忽略 - 日志通道是否记录了完整堆栈，否则线上出错时只能看到 “Parameter name must be string”，找不到调用位置
最易被忽略的是：Guard 方法返回值是否被后续代码依赖。如果校验后没 return 值或修改了原变量，而调用方仍按未校验逻辑走，健壮性反而下降。
