README

将值强制转换为各种数据类型的函数

此库包含将输入值转换为特定类型的函数，转换方式符合人们的预期（遵循最小惊讶原则）。如果转换不可行，或者转换方式有歧义，则强制转换失败。

例如，浮点数2.0可以被强制转换为整数2，因为2.0只是表示数字2的另一种方式。而尝试将浮点数2.1强制转换为整数将失败。特别是我们不会尝试猜测是否应该进行某种舍入，或者舍入的方向。输入2.1不表示整数，这就是全部。

对于每种目标数据类型，有4个函数，它们在处理null输入和如何处理失败的强制转换方面有所不同。

版本1

Coerce::toString($input, &$output): bool
Coerce::toInt($input, &$output): bool
Coerce::toFloat($input, &$output): bool
Coerce::toArrayKey($input, &$output): bool
Coerce::toBool($input, &$output): bool

在这个版本中，返回值是一个布尔值，表示强制转换是否成功（强制转换的值存储在$output参数中）。

当输入数据来自不可信的来源，因此期望失败的强制转换，并且代码应始终优雅地处理失败时，这个版本将更有用。

第一个参数$input按值传递，包含要强制转换的值（任何类型）。第二个参数$output按引用传递 - 如果强制转换可行，强制转换的结果将填充到$output中。根据目标类型，可能接受其他附加参数 - 请参阅以下特定函数的说明。

函数的返回值是布尔值，true表示强制转换可行，false表示否则。如果函数返回false，则应将$output的值视为无效并忽略。

版本2

Coerce::toStringOrFail($input): string
Coerce::toIntOrFail($input): int
Coerce::toFloatOrFail($input): float
Coerce::toArrayKeyOrFail($input): int|string
Coerce::toBoolOrFail($input): bool

在这个版本中，强制转换的值是函数的返回值，如果强制转换失败，则抛出InvalidArgumentException异常。

当输入数据来自可信的来源，因此期望强制转换通常成功，而失败是一个异常事件，可能表明代码中的其他地方有错误时，这个版本将更有用。

版本3

Coerce::toStringOrNull($input, &$output): bool
Coerce::toIntOrNull($input, &$output): bool
Coerce::toFloatOrNull($input, &$output): bool
Coerce::toArrayKeyOrNull($input, &$output): bool
Coerce::toBoolOrNull($input, &$output): bool

这个版本与版本1相同，但也可以接受null值。因此，如果输入是null或空字符串，输出也将是null，函数将返回true。

版本4

本版本与版本3相同，除了也接受空值。因此，如果输入为null或空字符串，函数将返回null。

示例

表单验证，其中用户在$_POST中的输入不可信

use MadisonSolutions\Coerce\Coerce;

if (! Coerce::toInt($_POST['age'] ?? null, $age)) {
    die("Age must be an integer");
}
// $age is definitely now an integer, but might be negative
if ($age < 0) {
    die("Age must be positive");
}
echo "The user is {$age} years old";

必须存储在字符串数据库字段中的布尔值

use MadisonSolutions\Coerce\Coerce;

$sql = "SELECT option_value FROM options WHERE option_name = 'show_vat_on_prices'";
$show_vat = Coerce::toBoolOrFail($db->get_first_value($sql));
// $show_vat is definitely a boolean, otherwise an exception would have been thrown
if ($show_vat) {
    $price = $price * 1.2;
}
...

// saving the value back to the database
$sql = "UPDATE options SET option_value = ? WHERE option_name = 'show_vat_on_prices'";
$db->update($sql, Coerce::toStringOrFail($show_vat));
// The value send to the database was definitely a string representation of the boolean $show_vat flag - either 'true' or 'false'

函数

Coerce::toString($input, &$output, bool $reject_bool = false)

将值强制转换为字符串。

空值将被强制转换为空字符串（除非使用toStringOrNull，在这种情况下它将强制转换为NULL）。
布尔值将被强制转换为字符串'true'或'false'（除非$reject_bool=true）。
整数和浮点数将被强制转换为它们的标准字符串表示。
不尝试将数组输入强制转换为字符串 - 函数将返回false。
只有当对象具有定义的__toString()方法时，才会强制转换对象，即类创建者有特定的字符串表示并明确定义。

Coerce::toInt($input, &$output, bool $reject_bool = false, bool $round_floats = false, bool $reject_negative = false, bool $reject_zero = false)

将值强制转换为整数。

空值不会被强制转换 - 函数将返回false（除非使用toIntOrNull）。
数组和对象不会被强制转换 - 函数将返回false。
布尔值true将被强制转换为1，而false将被强制转换为0（除非$reject_bool=true）。
如果输入值是整数或浮点数的字符串表示，则将强制转换该值。例如，浮点数4.0，字符串'4.0'或字符串'4'都将被强制转换为整数4。
非整数的数值字符串或浮点数将无法进行强制转换，除非$round_floats=true，在这种情况下，强制转换的值将是最近的整数。
如果设置了可选的$reject_negative标志，则负数将无法进行强制转换。
如果设置了可选的$reject_zero标志，则零将无法进行强制转换。

Coerce::toFloat($input, &$output, bool $reject_bool = false)

将值强制转换为浮点数。

空值不会被强制转换 - 函数将返回false（除非使用toFloatOrNull）。
数组和对象不会被强制转换 - 函数将返回false。
布尔值true将被强制转换为1.0，而false将被强制转换为0.0（除非$reject_bool=true）。
数值字符串将被强制转换为它们的浮点值。
如果输入在技术上属于浮点类型，但不是有限的（例如NAN或INF），则该值将无法进行强制转换，并且函数将返回false。

Coerce::toArrayKey($input, &$output)

将值强制转换为适合用作PHP数组键（字符串或整数）的类型。

空值不会被强制转换 - 函数将返回false（除非使用toArrayKeyOrNull）。
数组和对象不会被强制转换 - 函数将返回false。
布尔值不会被强制转换，因为使用字符串（'true'，'false'）还是整数（1，0）作为键存在歧义。
表示整数的字符串或浮点数将被强制转换为整数。
表示非整数值的浮点数将转换为字符串，用于作为数组键。
整数或任何不表示整数的字符串将被返回以供作为数组键使用。

Coerce::toBool($input, &$output)

将值强制转换为布尔值。

空值不会被强制转换 - 函数将返回false（除非使用toBoolOrNull）。
数组和对象不会被强制转换 - 函数将返回false。
数值（整数或浮点数）正好等于零将被强制转换为布尔值false。
数值（整数或浮点数）正好等于一将被强制转换为布尔值true。
所有其他数值值将无法进行强制转换 - 函数将返回false。
以下字符串（不区分大小写）将被强制转换为布尔值true：'1' 'true' 't' 'yes' 'y' 'on'。
以下字符串（不区分大小写）将被强制转换为布尔值false：'0' 'false' 'f' 'no' 'n' 'off'。
所有其他字符串值将不会被强制转换 - 函数将返回 false。

madison-solutions / coerce

维护者

详细信息

README

版本1

版本2

版本3

版本4

示例

函数