如何优雅地管理Laravel模型状态历史？Spatie/Laravel-Model-Status轻松搞定！

可以通过一下地址学习composer：学习地址

引言：状态管理的“甜蜜”与“烦恼”

在日常的 web 应用开发中，为模型（model）添加状态几乎是不可避免的需求。想象一下，一个电商平台中的订单，从用户下单到商品送达，会经历“待支付”、“已支付”、“备货中”、“已发货”、“已完成”、“已取消”等一系列状态。最初，我们可能会简单地在 orders 表中添加一个 status 字段来记录当前状态。

// Order.php
class Order extends Model
{
    // ...
    protected $fillable = ['status'];
}

// 设置状态
$order->status = 'paid';
$order->save();

这种方法在需求简单时确实“甜蜜”又高效。然而，随着业务的深入，新的“烦恼”接踵而至：

1. 历史追溯困难： 如果一个订单从“待支付”变为“已取消”，再变为“已退款”，我们如何知道它曾经经历过哪些状态？什么时候变更的？
2. 变更原因记录： 订单被取消的原因是什么？是用户主动取消，还是库存不足导致？仅仅一个状态字段无法承载这些额外信息。
3. 复杂查询： 如何查询所有“曾经”处于“待支付”状态的订单？或者查询所有“当前”处于“待审核”但“从未”被拒绝的用户？

面对这些挑战，传统的单字段方案捉襟见肘。我们可能需要手动创建 order_statuses 这样的关联表，记录 order_id、status_name、reason、created_at 等字段，并手动编写复杂的逻辑来维护这些数据和执行查询。这不仅增加了开发成本，也使得代码变得臃肿且难以维护。

Spatie/Laravel-Model-Status：优雅的解决方案

幸运的是，Laravel 生态系统中有许多优秀的包可以帮助我们解决这类问题。今天我们要介绍的 spatie/laravel-model-status 就是其中一颗璀璨的明珠。它由知名的 Spatie 团队开发，提供了一种优雅、可扩展的方式来为 Eloquent 模型管理状态及其历史。

这个包的核心思想是：将模型的状态变更作为一个独立的实体进行记录，每个状态记录都可以包含名称、原因以及时间戳。这样，你不仅能轻松获取模型的当前状态，还能追溯其完整的状态变更历史，并记录每次变更的详细原因。

安装与配置

使用 Composer 安装 spatie/laravel-model-status 包非常简单：

composer require spatie/laravel-model-status

安装完成后，你需要发布并运行迁移文件，以创建存储状态信息的 statuses 表：

php artisan vendor:publish --provider="Spatie\ModelStatus\ModelStatusServiceProvider" --tag="migrations"
php artisan migrate

你还可以选择发布配置文件 config/model-status.php，以便自定义状态模型或关联字段名，不过通常默认配置已经足够使用：

php artisan vendor:publish --provider="Spatie\ModelStatus\ModelStatusServiceProvider" --tag="config"

核心功能与实践

要让你的 Eloquent 模型拥有状态管理能力，只需在其模型类中引入 Spatie\ModelStatus\HasStatuses Trait：

// app/Models/Order.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Spatie\ModelStatus\HasStatuses; // 引入 Trait

class Order extends Model
{
    use HasStatuses; // 使用 Trait

    protected $fillable = ['name', 'amount']; // 示例字段
    // ...
}

现在，你的 Order 模型就具备了强大的状态管理能力！

1. 设置新状态

你可以轻松地为模型设置新状态，并可选地附带一个变更原因：

$order = Order::create(['name' => '商品A', 'amount' => 100]);

// 设置初始状态
$order->setStatus('pending_payment'); // 订单待支付

// 订单已支付
$order->setStatus('paid');

// 订单已取消，并记录原因
$order->setStatus('cancelled', '用户主动取消');

// 订单已退款，并记录原因
$order->setStatus('refunded', '商品缺货导致退款');

每一次 setStatus 调用都会在 statuses 表中新增一条记录，完美地记录了状态变更的历史和原因。

2. 获取状态信息

你可以通过多种方式获取模型的状态：

• 获取当前状态名称（字符串）：

  echo $order->status; // 输出：refunded

  登录后复制

• 获取当前状态对象（包含更多信息）：

  $currentStatus = $order->status(); // 返回 Spatie\ModelStatus\Status 实例
  echo $currentStatus->name;   // 输出：refunded
  echo $currentStatus->reason; // 输出：商品缺货导致退款

  登录后复制

  $order->latestStatus() 方法与 $order->status() 效果相同。

• 获取特定名称的最新状态： 如果你想知道订单最近一次被取消的原因，可以这样做：

  $cancelledStatus = $order->latestStatus('cancelled');
  echo $cancelledStatus->reason; // 输出：用户主动取消

  登录后复制

• 获取所有状态变更历史：

  $allStatuses = $order->statuses; // 返回所有关联的 Spatie\ModelStatus\Status 集合
  foreach ($allStatuses as $status) {
      echo "状态: {$status->name}, 原因: {$status->reason}, 时间: {$status->created_at}\n";
  }

  登录后复制

3. 查询模型（Scope）

包还提供了强大的查询 Scope，让你能轻松地根据状态筛选模型：

• 查询当前处于特定状态的模型：

  // 查询所有当前状态为 'pending_payment' 的订单
  $pendingOrders = Order::currentStatus('pending_payment')->get();
  
  // 查询当前状态为 'paid' 或 'refunded' 的订单
  $processedOrders = Order::currentStatus(['paid', 'refunded'])->get();

  登录后复制

• 查询当前不处于特定状态的模型：

  // 查询所有当前状态不是 'cancelled' 的订单
  $activeOrders = Order::otherCurrentStatus('cancelled')->get();

  登录后复制

• 检查模型是否“曾经”或“从未”拥有某个状态：

  $order->setStatus('pending');
  $order->setStatus('processing');
  
  echo $order->hasEverHadStatus('pending') ? 'Yes' : 'No'; // 输出：Yes
  echo $order->hasEverHadStatus('completed') ? 'Yes' : 'No'; // 输出：No
  
  echo $order->hasNeverHadStatus('completed') ? 'Yes' : 'No'; // 输出：Yes

  登录后复制

为什么选择 Spatie/Laravel-Model-Status？

1. 开箱即用： 简单的 Composer 安装和 Trait 引入，即可获得强大的状态管理能力。
2. 历史可追溯： 自动记录所有状态变更，方便审计和问题排查。
3. 附带原因： 允许为每次状态变更添加详细理由，增强数据上下文。
4. 强大查询： 内置的 Scope 使得基于状态的复杂查询变得异常简单。
5. 代码整洁： 将状态管理逻辑从业务模型中解耦，保持模型代码的简洁性。
6. Spatie 品质保证： Spatie 团队以其高质量、高维护性的开源包而闻名，使用他们的包通常意味着更少的坑和更好的支持。

总结

spatie/laravel-model-status 包是 Laravel 项目中处理模型状态管理的绝佳选择。它将一个看似简单却容易变得复杂的业务需求，通过优雅的设计和强大的功能，变得易于实现和维护。如果你在项目中遇到了需要跟踪状态历史、记录变更原因或进行复杂状态查询的场景，那么这个包无疑是你的救星。它不仅能帮助你写出更清晰、更健壮的代码，还能显著提升你的开发效率。赶快在你的下一个 Laravel 项目中尝试一下吧！

以上就是如何优雅地管理Laravel模型状态历史？Spatie/Laravel-Model-Status轻松搞定！的详细内容，更多请关注php中文网其它相关文章！