Laravel教程：精确计算和展示关联任务的总计时长 (HH:MM)

本教程详细介绍了如何在Laravel应用中，利用Eloquent关系和Carbon库，精确计算并以“小时:分钟”格式（HH:MM）展示关联任务的总计时长。我们将探讨如何为单个计时器计算分钟数，然后聚合所有关联计时器的总时长，并解决常见的格式化陷阱，确保输出结果的准确性和可读性。

在项目管理或时间跟踪应用中，准确计算并展示任务的总耗时是一个常见需求。当一个任务包含多个计时器（Timers），每个计时器记录了一段开始和结束时间时，我们需要将这些分散的时长聚合起来，并以用户友好的“小时:分钟”（HH:MM）格式呈现。本文将详细阐述如何在Laravel中实现这一功能。

理解问题：错误的计时格式化

在聚合多个计时器的总时长时，一个常见的错误是直接将总分钟数传递给 date('i:s', $totalMinutes) 函数。date() 函数的第二个参数期望的是一个Unix时间戳。如果 $totalMinutes 是例如 70（分钟），date('i:s', 70) 会将其解释为从Unix纪元（1970年1月1日00:00:00 UTC）起经过了70秒，然后格式化这70秒为 01:10（1分钟10秒），而非我们期望的“1小时10分钟”。这会导致结果严重偏离预期。

为了正确地将总分钟数转换为 HH:MM 格式，我们需要一个方法来创建一个“时间戳”，它能正确反映这些总分钟数所代表的小时和分钟。

解决方案：分步实现

我们将通过两个Eloquent模型（TsTimer 和 TsTask）来逐步构建解决方案。

步骤一：定义单个计时器时长（TsTimer 模型）

首先，确保每个独立的计时器能够计算出其自身的持续时间（以分钟为单位）。这通常通过在模型中定义一个访问器（Accessor）来完成。

在 TsTimer 模型中，我们需要将 start 和 end 字段定义为 datetime 类型，以便Carbon实例能够进行时间计算。getTotalAttribute 访问器将计算 start 和 end 之间的时间差。

芦笋演示

一键出成片的录屏演示软件，专为制作产品演示、教学课程和使用教程而设计。

34

查看详情

// app/Models/TsTimer.php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Carbon\Carbon; // 确保引入 Carbon

class TsTimer extends Model
{
    use HasFactory;

    // 将 'total' 访问器添加到模型数组表示中
    public $appends = ['total'];

    // 将 'start' 和 'end' 字段自动转换为 Carbon 实例
    public $casts = [
        'start' => 'datetime',
        'end' => 'datetime',
    ];

    /**
     * 定义与 TsTask 模型的关系
     */
    public function task()
    {
        return $this->belongsTo(TsTask::class);
    }

    /**
     * 定义与 User 模型的关系
     */
    public function user()
    {
        return $this->belongsTo(User::class);
    }

    /**
     * 获取单个计时器的总时长（分钟）。
     * 如果计时器未结束（end 为空），则返回0。
     *
     * @return int
     */
    public function getTotalAttribute(): int
    {
        if ($this->end) {
            return $this->start->diffInMinutes($this->end);
        }
        return 0; // 计时器未结束，返回0分钟
    }
}

解释：

• $casts 属性确保 start 和 end 字段在从数据库取出时自动转换为 Carbon 实例，这使得时间计算变得非常方便。
• getTotalAttribute() 方法利用 Carbon 实例的 diffInMinutes() 方法计算两个时间点之间的分钟差。
• 如果 end 时间为空（表示计时器仍在运行），我们返回 0，可以根据实际业务需求调整此逻辑（例如，返回从 start 到当前时间的分钟数）。

步骤二：聚合任务总时长并正确格式化（TsTask 模型）

接下来，在 TsTask 模型中，我们需要聚合所有关联 TsTimer 的总时长，并将其格式化为 HH:MM。

// app/Models/TsTask.php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class TsTask extends Model
{
    use HasFactory;

    // 将 'total' 访问器添加到模型数组表示中
    // 注意：这里的 'total' 将覆盖或与 TsTimer 的 'total' 区分开
    public $appends = ['total_duration_formatted']; // 建议使用更明确的名称，避免混淆

    /**
     * 定义与 TsProject 模型的关系
     */
    public function project()
    {
        return $this->belongsTo(TsProject::class);
    }

    /**
     * 定义与 TsTimer 模型的一对多关系
     */
    public function timers()
    {
        return $this->hasMany(TsTimer::class, 'task_id');
    }

    /**
     * 获取任务所有关联计时器的总时长，并以 HH:MM 格式返回。
     *
     * @return string
     */
    public function getTotalDurationFormattedAttribute(): string
    {
        // 聚合所有关联计时器的 'total' 访问器返回的分钟数
        $totalMinutes = $this->timers->sum('total');

        // 使用 mktime 函数创建一个基于总分钟数的时间戳
        // mktime(hour, minute, second, month, day, year)
        // 这里我们只关心 minute 参数，将总分钟数传递给它
        // date() 函数会根据这个时间戳正确计算出小时和分钟
        return date('H:i', mktime(0, $totalMinutes));
    }
}

解释：

• $this-youjiankuohaophpcntimers->sum('total')：这是关键一步。Eloquent 集合的 sum() 方法可以接受一个属性名或访问器名作为参数。在这里，它会遍历 TsTask 关联的所有 TsTimer 模型，并调用每个 TsTimer 实例的 getTotalAttribute() 方法来获取其分钟数，然后将这些分钟数累加起来，得到任务的总分钟数 $totalMinutes。
• mktime(0, $totalMinutes)：这是解决格式化问题的核心。mktime() 函数用于创建一个Unix时间戳。通过将小时和秒设置为 0，并将 $totalMinutes 传递给 minute 参数，我们创建了一个时间戳，它代表了从某个基准时间（通常是当天午夜）开始经过了 $totalMinutes 分钟。例如，如果 $totalMinutes 是 70，mktime(0, 70) 会创建一个时间戳，该时间戳表示 1小时10分钟。
• date('H:i', ...)：现在，将 mktime() 生成的正确时间戳传递给 date() 函数，并使用 H:i 格式，即可准确地得到 HH:MM 格式的总时长。H 代表24小时制的小时（00-23），i 代表分钟（00-59）。

示例应用

在控制器或视图中，你可以像访问其他模型属性一样访问这个格式化的总时长：

// 例如在控制器中
use App\Models\TsTask;

public function showTask($taskId)
{
    // 确保预加载 timers 关系，避免 N+1 查询问题
    $task = TsTask::with('timers')->findOrFail($taskId);

    // 获取格式化的总时长
    $totalDuration = $task->total_duration_formatted; // 使用我们定义的访问器名称

    // 传递给视图
    return view('tasks.show', compact('task', 'totalDuration'));
}

// 在 Blade 视图中
<div>
    <h1>任务详情：{{ $task->name }}</h1>
    <p>总耗时：{{ $totalDuration }}</p>
    {{-- 或者直接使用 --}}
    <p>总耗时：{{ $task->total_duration_formatted }}</p>
</div>

注意事项

1. 性能优化（N+1 问题）：当查询多个 TsTask 并希望显示它们的总时长时，请务必使用 with('timers') 进行预加载，以避免 N+1 查询问题。

   $tasks = TsTask::with('timers')->get();
   foreach ($tasks as $task) {
       echo $task->total_duration_formatted;
   }

   登录后复制
2. 计时器未结束的处理：TsTimer 模型中的 getTotalAttribute 已经处理了 end 为空的情况。如果业务逻辑需要将正在进行的计时器的时间也计算在内（例如，从 start 到当前时间），你需要修改 TsTimer 中的逻辑。
3. 时区问题：Carbon 库在处理日期时间时通常会考虑时区。如果你的应用程序涉及多个时区，请确保数据库、应用程序配置和用户偏好设置中的时区一致。
4. $appends 的使用：将访问器添加到 $appends 数组中，会使其在模型被转换为数组或 JSON 时自动包含该属性。这在API响应中非常有用，但如果不需要，可以省略，并通过 $task->total_duration_formatted 直接访问。
5. 访问器命名：为了避免与 TsTimer 模型中的 total 访问器混淆，我们为 TsTask 模型中的总时长访问器使用了更明确的名称 total_duration_formatted。在实际项目中，建议使用清晰、避免歧义的命名约定。

总结

通过以上步骤，我们成功解决了在Laravel中聚合关联计时器总时长并以 HH:MM 格式正确显示的问题。核心在于利用Eloquent的关系和访问器来计算单个计时器的分钟数，然后使用 sum() 方法聚合这些分钟数，最后借助 mktime() 函数巧妙地将总分钟数转换为 date() 函数能够正确解析的时间戳，从而实现精确的 HH:MM 格式化。这种方法既保证了代码的清晰性，又解决了常见的格式化陷阱，为用户提供了准确易读的时间信息。

以上就是Laravel教程：精确计算和展示关联任务的总计时长 (HH:MM)的详细内容，更多请关注php中文网其它相关文章！