PHP ValueError

最后修改于 2025 年 3 月 11 日

在本文中，我们探讨了 PHP 中的 ValueError。 当函数接收到类型正确但值无效的参数时，会抛出 ValueError。 这种异常通常用于严格类型化的 PHP 代码中，以强制执行值约束。

基本定义

ValueError 是 PHP 中的一个内置异常，当函数接收到具有无效值的参数时，会抛出该异常。 它通常与严格类型声明结合使用，以确保值满足特定标准。

基本 ValueError

此示例验证电子商务系统中的折扣百分比。

<?php

declare(strict_types=1);

function applyDiscount(float $price, float $discount): float
{
    if ($discount < 0 || $discount > 100) {
        throw new ValueError("Discount must be between 0 and 100.");
    }
    return $price * (1 - $discount / 100);
}

try {
    echo applyDiscount(50.0, 150.0);
} catch (ValueError $e) {
    echo "Caught ValueError: " . $e->getMessage();
}

在这种实际场景中，applyDiscount 函数计算折扣后的价格。 如果折扣百分比超出 0 到 100 的有效范围，则会抛出 ValueError，这是电子商务应用程序中的常见业务规则。

try-catch 块捕获异常并输出错误消息。 这种方法确保无效的折扣不会默默地产生不正确的结果，从而提高定价逻辑的可靠性。

$ php main.php
Caught ValueError: Discount must be between 0 and 100.

无效的数组键

此示例通过索引从购物车中检索订单项。

<?php

declare(strict_types=1);

function getCartItem(array $cart, int $index): string
{
    if ($index < 0 || $index >= count($cart)) {
        throw new ValueError("Invalid cart item index.");
    }
    return $cart[$index];
}

try {
    $cart = ["Shirt", "Pants", "Shoes"];
    echo getCartItem($cart, 3);
} catch (ValueError $e) {
    echo "Caught ValueError: " . $e->getMessage();
}

在这里，getCartItem 函数根据索引从购物车数组中获取一个项目。 如果索引为负数或超出数组的长度，则会抛出 ValueError，从而防止越界访问。

这在电子商务或库存系统中很有用，您需要确保项目检索保持在有效范围内。 try-catch 块优雅地处理错误，告知用户无效输入，而不是崩溃或返回未定义的结果。

$ php main.php
Caught ValueError: Invalid cart item index.

无效的枚举值

此示例验证事务系统中的付款状态。

<?php

declare(strict_types=1);

enum PaymentStatus: string
{
    case Pending = 'pending';
    case Completed = 'completed';
}

function processPayment(PaymentStatus $status): void
{
    echo "Processing payment with status: " . $status->value;
}

try {
    processPayment(PaymentStatus::from('failed'));
} catch (ValueError $e) {
    echo "Caught ValueError: " . $e->getMessage();
}

在此示例中，我们定义了一个 PaymentStatus 枚举，其中包含支付系统的有效值。 processPayment 函数期望一个 PaymentStatus 枚举值，当 PaymentStatus::from() 接收到无效值（例如“failed”）时，PHP 会自动抛出 ValueError。

这对于财务应用非常实用，在财务应用中，必须严格控制支付状态。 try-catch 块捕获错误，允许系统优雅地处理无效状态，而无需继续使用不正确的数据。

$ php main.php
Caught ValueError: "failed" is not a valid backing value for enum PaymentStatus

无效的日期

此示例验证预订系统的预订日期。

<?php

declare(strict_types=1);

function bookDate(string $date): DateTime
{
    $dateTime = DateTime::createFromFormat('Y-m-d', $date);
    if (!$dateTime || $dateTime->format('Y-m-d') !== $date) {
        throw new ValueError("Invalid or non-existent date.");
    }
    return $dateTime;
}

try {
    echo bookDate('2025-04-31')->format('Y-m-d');
} catch (ValueError $e) {
    echo "Caught ValueError: " . $e->getMessage();
}

bookDate 函数从“Y-m-d”格式的日期字符串创建 DateTime 对象。 如果日期无效（例如，4 月 31 日不存在）或与预期格式不匹配，则会抛出 ValueError，从而确保仅处理有效日期。

这对于酒店或活动预订系统来说是一个现实的场景，无效的日期可能会扰乱日程安排。 额外的 format('Y-m-d') 检查可确保已解析的日期与输入匹配，从而捕获非现有日期等边缘情况。

try-catch 块向用户或系统提供反馈，防止静默失败并确保稳健的日期处理。

$ php main.php
Caught ValueError: Invalid or non-existent date.

无效的整数范围

此示例在库存系统中设置产品数量。

<?php

declare(strict_types=1);

function setStockQuantity(int $quantity): void
{
    if ($quantity < 0 || $quantity > 1000) {
        throw new ValueError("Stock quantity must be between 0 and 1000.");
    }
    echo "Stock set to: " . $quantity;
}

try {
    setStockQuantity(-5);
} catch (ValueError $e) {
    echo "Caught ValueError: " . $e->getMessage();
}

在此示例中，setStockQuantity 函数强制执行产品库存的有效范围（0 到 1000）。 如果数量为负数或超出允许的最大值，则会抛出 ValueError，这对于库存管理非常实用。

这确保库存水平保持现实，并防止出现负库存等错误，这些错误可能会混淆订单处理。 try-catch 块捕获异常，允许系统做出适当的响应，而不是继续使用无效数据。

$ php main.php
Caught ValueError: Stock quantity must be between 0 and 1000.

无效的字符串长度

此示例在目录系统中验证产品代码。

<?php

declare(strict_types=1);

function setProductCode(string $code): void
{
    if (strlen($code) < 3 || strlen($code) > 10) {
        throw new ValueError("Product code must be 3-10 characters.");
    }
    echo "Product code set to: " . $code;
}

try {
    setProductCode("AB");
} catch (ValueError $e) {
    echo "Caught ValueError: " . $e->getMessage();
}

setProductCode 函数确保产品代码的长度在 3 到 10 个字符之间，这是目录或 SKU 系统中的常见要求。 如果违反长度约束，则会抛出 ValueError。

这对于维护数据库或电子商务平台中一致的产品标识符很有用。 try-catch 块处理异常，提供清晰的反馈以防止保存无效代码。

$ php main.php
Caught ValueError: Product code must be 3-10 characters.

无效的电子邮件格式

此示例在用户注册期间验证电子邮件。

<?php

declare(strict_types=1);

function registerUser(string $email): void
{
    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
        throw new ValueError("Invalid email address format.");
    }
    echo "User registered with email: " . $email;
}

try {
    registerUser("user@.com");
} catch (ValueError $e) {
    echo "Caught ValueError: " . $e->getMessage();
}

在这种情况下，registerUser 函数使用 PHP 的 filter_var 函数验证电子邮件地址。 如果电子邮件格式无效，则会抛出 ValueError，确保仅接受正确的电子邮件地址。

这是用户注册工作流程中的一项关键检查，以防止格式错误的数据进入系统。 try-catch 块捕获错误，允许应用程序提示用户更正其输入。

$ php main.php
Caught ValueError: Invalid email address format.

无效的文件大小限制

此示例在媒体系统中强制执行文件上传大小限制。

<?php

declare(strict_types=1);

function uploadFile(int $sizeInBytes): void
{
    $maxSize = 5 * 1024 * 1024; // 5MB
    if ($sizeInBytes <= 0 || $sizeInBytes > $maxSize) {
        throw new ValueError("File size must be between 1 byte and 5MB.");
    }
    echo "File of $sizeInBytes bytes uploaded.";
}

try {
    uploadFile(6 * 1024 * 1024); // 6MB
} catch (ValueError $e) {
    echo "Caught ValueError: " . $e->getMessage();
}

uploadFile 函数检查文件的大小是否在可接受的范围内（1 字节到 5MB）。 如果大小无效（例如，零、负数或超出限制），则会抛出 ValueError。

这对于文件上传系统非常实用，在这种系统中，大小限制可以保护服务器存储并确保可用性。 try-catch 块处理异常，将违规情况告知用户或系统，而不会崩溃。

通过定义明确的限制（此处为 5MB），该函数强制执行一项策略，该策略可以根据应用程序的需要进行调整，使其适用于实际使用。

$ php main.php
Caught ValueError: File size must be between 1 byte and 5MB.

无效的货币代码

此示例验证支付网关中的货币代码。

<?php

declare(strict_types=1);

function setCurrency(string $code): void
{
    $validCurrencies = ['USD', 'EUR', 'GBP'];
    if (!in_array($code, $validCurrencies)) {
        throw new ValueError("Invalid currency code.");
    }
    echo "Currency set to: " . $code;
}

try {
    setCurrency('JPY');
} catch (ValueError $e) {
    echo "Caught ValueError: " . $e->getMessage();
}

在此示例中，setCurrency 函数确保货币代码与预定义的受支持货币列表匹配。 如果代码无效（例如，在这种情况下为“JPY”），则会抛出 ValueError。

这在仅接受特定货币的支付处理系统中很有用。 in_array 检查提供了一种简单而有效的方法，可以根据白名单验证输入。

try-catch 块捕获错误，允许应用程序拒绝不受支持的货币并提示用户选择一个有效的选项，从而增强金融运营中的数据完整性。

$ php main.php
Caught ValueError: Invalid currency code.

来源

PHP ValueError - 文档

在本文中，我们展示了如何在 PHP 中处理 ValueError。 此异常对于在严格类型化的代码中强制执行值约束很有用。

作者

我叫 Jan Bodnar，是一位充满激情的程序员，拥有丰富的编程经验。 自 2007 年以来，我一直在撰写编程文章。 迄今为止，我已经撰写了 1,400 多篇文章和 8 本电子书。 我拥有超过十年的编程教学经验。

列出 所有 PHP 教程。