README

此库包含高效的断言，用于测试方法输入和输出。使用这些断言，您可以大大减少编写安全实现的编码量。

如果失败，Assert类中的所有断言都会抛出Webmozart\Assert\InvalidArgumentException异常。

常见问题解答

与beberlei/assert相比有什么区别？

此库深受 Benjamin Eberlei 的优秀assert 包的启发，但解决了无法在不破坏向后兼容性的情况下在那里修复的错误消息可用性问题。

默认情况下，此包提供可用的错误消息。但是，您也可以轻松编写自定义错误消息

Assert::string($path, 'The path is expected to be a string. Got: %s');

在beberlei/assert中，每个断言的%s占位符的顺序都不同。相比之下，此包为所有断言提供了一致的占位符顺序

• %s：被测试的值作为字符串，例如"/foo/bar"。
• %2$s、%3$s、...：额外的断言特定值，例如最小/最大长度、允许值等。

检查断言的源代码，以了解有关其他可用占位符的详细信息。

安装

使用Composer安装此包

composer require webmozart/assert

示例

use Webmozart\Assert\Assert;

class Employee
{
    public function __construct($id)
    {
        Assert::integer($id, 'The employee ID must be an integer. Got: %s');
        Assert::greaterThan($id, 0, 'The employee ID must be a positive integer. Got: %s');
    }
}

如果您创建一个具有无效 ID 的员工，则会抛出异常

new Employee('foobar');
// => Webmozart\Assert\InvalidArgumentException:
//    The employee ID must be an integer. Got: string

new Employee(-10);
// => Webmozart\Assert\InvalidArgumentException:
//    The employee ID must be a positive integer. Got: -10

断言

Assert类提供了以下断言

类型断言

比较断言

字符串断言

在执行以下任何断言之前，您应该使用Assert::string()检查值是否为字符串。

文件断言

对象断言

数组断言

函数断言

集合断言

所有上述断言都可以使用all*()前缀来测试数组或\Traversable的内容

Assert::allIsInstanceOf($employees, 'Acme\Employee');

可为空的断言

所有上述断言都可以使用nullOr*()前缀来运行断言，前提是值不是null

Assert::nullOrString($middleName, 'The middle name must be a string or null. Got: %s');

扩展 Assert

Assert类附带了一些方法，可以通过重写它们来更改类的行为。您还可以扩展它以添加自己的断言。

重写方法

重写以下方法允许您更改断言的行为

• public static function __callStatic($name, $arguments)
  • 此方法用于“创建”断言的nullOr和all版本。
• protected static function valueToString($value)
  • 此方法用于错误消息，将值转换为用于显示的字符串值。例如，您可以使用此方法表示具有__toString方法的值对象。
• protected static function typeToString($value)
  • 此方法用于错误消息，将值转换为表示其类型的字符串。
• protected static function strlen($value)
  • 此方法用于计算相关方法的字符串长度，如果可用且有用，则使用 mb_strlen。
• 受保护静态函数 reportInvalidArgument($message)
  • 当断言失败时调用此方法，带有指定的错误信息。在这里，您可以抛出自己的异常或记录一些信息。

静态分析支持

在适用的情况下，断言函数会标注以支持 Psalm 的 断言语法。需要一个专门的 PHPStan 插件 来正确支持类型。

作者

• Bernhard Schussek，又称 @webmozart
• 社区贡献者

贡献

欢迎对包的贡献！

• 在 问题追踪器 上报告您找到的任何错误或问题。
• 您可以在包的 Git 仓库 中获取源代码。

许可证

此包的所有内容均受 MIT 许可证 许可。