README

在进行长时间操作时，了解在任何给定时间点操作哪个部分正在执行，已完成多少工作，以及还剩下多少工作，对于用户体验和调试都很有用。

此包是一个存储此类数据的标准结构，它提供了一个易于使用的API，可以随时间跟踪数据，并将多种类型的进度合并在一起。

安装

composer require vanilla/garden-progress

使用

跟踪进度

use Garden\Progress\Progress;

$progress = new Progress();

$step1 = $progress->step("step1");

// Optional but completion is generally more easily tracked if you know how much work there is to do.
$step1->setTotal(count($thingsToDo));

// Track a bunch of work at once.
try {
    $thing->doWorkOnItems($thingsToDo);
    $step1->incrementSuccess(count($thingsToDo));
} catch (Exception $failed) {
    // Handle your error.
    $step1->incrementFailed(count($thingsToDo));
}

// Track specific IDs.
foreach ($thingsToDo as $thingID) {
    try {
        $thing->doThing($thingID);
        $step1->trackSuccessID($thingID);
    } catch (Throwable $e) {
        $step1->trackFailedID($thingID, $e);
    }
}

// Access current completion
$progress->step("step1")->completion->countFailed;
$progress->step("step1")->completion->countTotal;
$progress->step("step1")->completion->countSuccess;

$progress->step("step1")->transientData->successIDs;
$progress->step("step1")->transientData->failedIDs;
$progress->step("step1")->transientData->errorsByID[$someID]["message"] ?? null;

序列化和反序列化为JSON

use Garden\Progress\Progress;

// You dump it down to an array/json
$progress = new Progress();
$progress
    ->step("step1")
    ->setTotal(10)
    ->incrementSuccess(10);
$progress
    ->step("step2")
    ->setTotal(20)
    ->incrementFailed(20);
$json = json_encode($progress);

// And pull it back out again.
$fromJson = Progress::fromArray(json_decode($progress, true));

合并进度

进度旨在合并。每个步骤的完成和瞬态数据将合并。

use Garden\Progress\Progress;

$progress1 = new Progress();
$progress1->step("step1");

$progress2 = new Progress();
$progress2->step("step2");

$progress3 = new Progress();
$progress3->step("step2");
$progress3->step("step3");

$merged = $progress1->merge($progress2, $progress3);
// All these were merged together.
$merged->step("step1");
$merged->step("step2");
$merged->step("step3");

作业进度复杂示例

{
    // General label for the thing being progress.
    name: "Doing the job",
    // Many jobs may only have 1 step being tracked, but a more complex job may have multiple.
    steps: {
        // Steps are named
        "A step name": {
            name: "A step name",
            // Each step tracks progress.
            // Progress accumulates over time.
            completion: {
                countTotal: 54103,
                countComplete: 4200,
                countFailed: 4,
            },
            // Transient IDs can be useful for something watching a job progress intimately.
            // Only a small amount of these should ever accumulate in storage systems
            // As they could easily become too much in a large process.
            // Many types of jobs will not return this data at all.
            transientData: {
                successIDs: [51, 590, 131, 32],
                failedIDs: [12, 15, 43, 452],
                errorsByID: {
                    "452": {
                        message: "You do not have permission to modify this article",
                        code: 403,
                    },
                },
            },
        },
    },
}