README

PHP 断言

用于简化PHP中通过assert()进行防御性编程和设计合同（DbC）编程的库。

安装

打开终端，进入您的项目目录，并执行以下命令以将此包添加到依赖项

$ composer require fleshgrinder/assertion

此命令要求您全局安装Composer，如Composer文档中的安装章节中所述。

注意：请不要将此库作为开发需求安装，因为Composer不会在将库作为另一个库的依赖项安装时安装它们。您希望在所有时间执行断言，除了整个应用程序进入生产状态时；这通过配置管理。

用法

此库提供了一个单例静态类，可用于简化断言中的重复标量检查，并可在其基础上编写自定义检查。以下代码示例展示了基本用法

// Use built-in functions whenever possible.
assert(is_string($var), 'variable must be of type string.');
assert(Variable::isStringWithContent($var), 'variable must be of type string with content');
assert(Variable::isStringable($var), 'variable must be of type string or a convertible object');
assert(Variable::isStringableWithContent($var), 'variable must be of type string or a convertible object with content');

// Again, use built-in functions whenever possible.
assert($var === null || Variable::isInteger($var), 'variable must be NULL or an integer (ℤ)');
assert($var === null || Variable::isNaturalNumber($var), 'variable must be NULL or a natural number (ℕ₀)');
assert($var === null || Variable::isScalarPositiveNaturalNumber($var), 'variable must be NULL or a positive natural number (ℕ₁) of type int');

大浮点数

要验证大浮点数，需要PHP扩展BC Math。这不是必需的，但如果遇到大浮点数且扩展不可用，将触发一个E_USER_NOTICE错误。PHP必须使用--enable-bcmath标志编译，并且Windows系统上始终加载此扩展。

防御性编程/设计合同

“要有礼貌，永远不要断言

避免使用assert()机制，因为它可能会将三天的调试变成十分钟的调试。”

—— 如何编写不可维护的代码，Roedy Green。

请务必查看链接部分，并阅读所有来源，以了解断言的好处、何时使用它们以及何时不使用。如果您仍有疑问，请随时提出问题。

配置

断言需要适当配置，以便在开发期间以及生产期间有用。

开发

assert.exception = 1
zend.assertions  = 1

生产

assert.exception = 0
zend.assertions  = -1

注意

本库中没有重新定义PHP已经提供的默认函数。尽可能使用语言函数，例如：is_string、is_int、is_float、is_numeric 等。

然而，许多过滤器函数通过不需要额外参数的方法公开，例如整数和浮点数断言将它们的参数传递给过滤器函数，并设置适当的过滤器和选项。如果你确实需要正确的类型，请小心并考虑使用 is_int 和 is_float，如果你需要处理非常大的数字，请更加小心，在这些情况下再次使用此库，因为它将根据需要回退到 bcmath 函数，同时确保通过使用后台最合适的库来获得最佳性能。

常见问题解答

为什么这个类叫作“Variable”？

为了形成漂亮的英文句子，请看以下内容：

assert(Variable::isPositiveNaturalNumber($id));
// Assert variable (id) is (a) positive natural number.

为什么它是一个类，而不是一组过程式函数的集合？

因为PHP（composer）不支持过程式函数的延迟加载，并且在生产中包含文件没有意义。另一方面，使用类可以实现延迟加载。

为什么这个类不遵循PSR-4（以及相关的供应商前缀以避免冲突），而测试却遵循？

为了最小化在 assert 调用中的噪音和IDE（如PhpStorm）的额外工作，这些IDE会自动导入使用 use 语句的类，而这些语句与 assert 不太配合。我认为另一个类以通用的 variable 命名的可能性很低，因此得出结论，上述论据足以将类放入全局命名空间。

致谢

致谢：此库受到了 Drupal 的 Inspector类 的启发。

相关链接

• PHP组：“assert()”
• Steve McConnell：“代码大全：第2版”，2004年，Microsoft Press，960页。ISBN：0735619670。特别是第8.2节，但还有更多关于防御性编程和如何有效使用 assert() 的通用建议。
• Aki Tendo等人：“将断言添加到Drupal - 测试工具。”
• Jess (xjm) 等人：“[政策，无补丁] 定义在使用和测试断言的最佳实践，并在将断言添加到核心之前进行记录”
• Aki Tendo：“运行时断言已添加到Drupal核心”，2015年9月29日。
• Drupal贡献者：“良好格式错误倡议”，2015年3月6日。
• Stackoverflow贡献者：“断言应该留在生产代码中吗？”
• 维基百科贡献者：“断言（软件开发）”
• 维基百科贡献者：“设计合约”
• 维基百科贡献者：“异常处理”

许可证