Laravel Nova 定義 Metrics

Nova 的 metrics 可以幫助您快速了解應(yīng)用的關(guān)鍵業(yè)務(wù)指標(biāo)。例如，您可以定義一個(gè) metrics，用來顯示每天添加到應(yīng)用中的用戶總數(shù)或每周銷售額。

Nova 提供三種類型的內(nèi)置 metrics：值 metrics、趨勢(shì) metrics 和分區(qū) metrics。下面我們將學(xué)習(xí)每種類型的 metrics 并在演示它們的用法。

Value Metrics

Value metrics 可以展示單個(gè)值，如果需要，也可以顯示與上個(gè)周期間隔的比值。 例如，一個(gè) value metric 想顯示前三十天新用戶和 上個(gè)三十天新用戶的比值：

Value metrics 可以使用 nova:value Artisan 命令生成。默認(rèn) 所有新生成的 metrics 都會(huì)在 app/Nova/Metrics 目錄中：

php artisan nova:value NewUsers

一旦生成值 metric 類后，您就可以對(duì)其進(jìn)行自定義了。每個(gè)值 metric 都有一個(gè) calculate 方法，該方法返回了一個(gè) Laravel\Nova\Metrics\ValueResult 對(duì)象。Nova 附帶了各種幫助程序，可以快速生成結(jié)果。

下面的例子，我們使用 count 助手自動(dòng)對(duì)選定范圍的 Eloquent 模型執(zhí)行 count 查詢，并自動(dòng)對(duì) “上一個(gè)” 索引范圍計(jì)數(shù)。

<?php

namespace App\Nova\Metrics;

use App\User;
use Illuminate\Http\Request;
use Laravel\Nova\Metrics\Value;

class NewUsers extends Value
{
    /**
     * 計(jì)算 metric 的值。
     *
     * @param  \Illuminate\Http\Request  $request
     * @return mixed
     */
    public function calculate(Request $request)
    {
        return $this->count($request, User::class);
    }

    /**
     * 獲取 metric 的時(shí)間范圍。
     *
     * @return array
     */
    public function ranges()
    {
        return [
            30 => '30 Days',
            60 => '60 Days',
            365 => '365 Days',
            'MTD' => 'Month To Date',
            'QTD' => 'Quarter To Date',
            'YTD' => 'Year To Date',
        ];
    }

    /**
     * 獲取 metric 的 URI 鍵。
     *
     * @return string
     */
    public function uriKey()
    {
        return 'new-users';
    }
}

值查詢類型

值 metrics 不只是附帶一個(gè) count 助手。在構(gòu)建 metric 時(shí)，您還可以在構(gòu)建 metric 時(shí)使用各種其他聚合函數(shù)。

Average

average 方法可用于計(jì)算給定列與前一個(gè)時(shí)間間隔 / 范圍相比的平均值：

return $this->average($request, Post::class, 'word_count');

Sum

sum 方法可用于計(jì)算給定列與前一時(shí)間間隔 / 范圍的總和：

return $this->sum($request, Order::class, 'price');

Max

max 方法可用于計(jì)算給定列相對(duì)于前一時(shí)間間隔 / 范圍的最大值：

return $this->max($request, Order::class, 'total');

Min

min 方法可用于計(jì)算給定列相對(duì)于前一時(shí)間間隔 / 范圍的最小值：

return $this->min($request, Order::class, 'total');

值范圍

每個(gè)值度量類都包含一個(gè) ranges 方法。此方法確定值度量的范圍選擇菜單中的可用的范圍。數(shù)組的鍵確定應(yīng)包含在查詢中的天數(shù)，而值確定將放置在范圍選擇菜單中的「可讀的」文本。當(dāng)然，您根本不需要定義任何范圍：

/**
 * 獲取指標(biāo)可用范圍。
 *
 * @return array
 */
public function ranges()
{
    return [
        5 => '5 Days',
        10 => '10 Days',
        15 => '15 Days',
        'MTD' => 'Month To Date',
        'QTD' => 'Quarter To Date',
        'YTD' => 'Year To Date',
    ];
}

MTD / QTD / YTD 范圍鍵

您可以定制這些范圍以滿足您的需求；但是，如果您使用內(nèi)置的「月度至今」、「季度至今」、或 「年度至今」范圍，則不應(yīng)更改它們的鍵。

手動(dòng)構(gòu)建結(jié)果值

如果你不能使用自帶的查詢助手構(gòu)建您的 metric 值，你可以使用 result 和 previous 方法手動(dòng)為 metric 提供最終值：

return $this->result(100)->previous(50);

趨勢(shì) Metrics

趨勢(shì) metrics 通過折線圖顯示隨著時(shí)間變化的值。例如，趨勢(shì) metric 可能會(huì)顯示過去 30 天內(nèi)每天創(chuàng)建的新用戶數(shù)：

趨勢(shì)指標(biāo)可以使用 nova:trend Artisan 命令生成。默認(rèn)情況下，所有新指標(biāo)都將放在 app/Nova/Metrics 目錄中：

php artisan nova:trend UsersPerDay

生成趨勢(shì)度量類后，您就可以對(duì)其進(jìn)行自定義了。每個(gè)趨勢(shì)度量類都包含一個(gè) calculate 方法。這個(gè)方法應(yīng)該返回一個(gè) Laravel\Nova\Metrics\TrendResult 對(duì)象。不用擔(dān)心，Nova 附帶了各種幫助程序，可以快速生成結(jié)果。

在這個(gè)例子中，我們使用了 countByDays 幫助器，它會(huì)自動(dòng)對(duì)指定的 Eloquent 模型執(zhí)行一個(gè) count 查詢，用于選定的范圍和選定的間隔單位 (在這種情況下，天)：

<?php

namespace App\Nova\Metrics;

use App\User;
use Illuminate\Http\Request;
use Laravel\Nova\Metrics\Trend;

class UsersPerDay extends Trend
{
    /**
     * Calculate the value of the metric.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return mixed
     */
    public function calculate(Request $request)
    {
        return $this->countByDays($request, User::class);
    }

    /**
     * Get the ranges available for the metric.
     *
     * @return array
     */
    public function ranges()
    {
        return [
            30 => '30 Days',
            60 => '60 Days',
            90 => '90 Days',
        ];
    }

    /**
     * Get the URI key for the metric.
     *
     * @return string
     */
    public function uriKey()
    {
        return 'users-per-day';
    }
}

趨勢(shì)查詢類型

趨勢(shì) metrics 不只是附帶一個(gè) countByDays 助手。在構(gòu)建 metric 時(shí)，您還可以使用各種其他聚合函數(shù)和時(shí)間間隔。

Count

count 方法可用于計(jì)算給定列隨著時(shí)間變化的計(jì)數(shù)：

return $this->countByMonths($request, User::class);
return $this->countByWeeks($request, User::class);
return $this->countByDays($request, User::class);
return $this->countByHours($request, User::class);
return $this->countByMinutes($request, User::class);

Average

average 方法可用于計(jì)算給定列隨著時(shí)間變化的平均值：

return $this->averageByMonths($request, Post::class, 'word_count');
return $this->averageByWeeks($request, Post::class, 'word_count');
return $this->averageByDays($request, Post::class, 'word_count');
return $this->averageByHours($request, Post::class, 'word_count');
return $this->averageByMinutes($request, Post::class, 'word_count');

Sum

sum 方法可用于計(jì)算給定列隨著時(shí)間變化的總和：

return $this->sumByMonths($request, Order::class, 'price');
return $this->sumByWeeks($request, Order::class, 'price');
return $this->sumByDays($request, Order::class, 'price');
return $this->sumByHours($request, Order::class, 'price');
return $this->sumByMinutes($request, Order::class, 'price');

Max

max 方法可用于計(jì)算給定列隨著時(shí)間變化的最大值：

return $this->maxByMonths($request, Order::class, 'total');
return $this->maxByWeeks($request, Order::class, 'total');
return $this->maxByDays($request, Order::class, 'total');
return $this->maxByHours($request, Order::class, 'total');
return $this->maxByMinutes($request, Order::class, 'total');

Min

min 方法可用于計(jì)算給定列隨著時(shí)間變化的最小值：

return $this->minByMonths($request, Order::class, 'total');
return $this->minByWeeks($request, Order::class, 'total');
return $this->minByDays($request, Order::class, 'total');
return $this->minByHours($request, Order::class, 'total');
return $this->minByMinutes($request, Order::class, 'total');

趨勢(shì)范圍

每個(gè)趨勢(shì)度量標(biāo)準(zhǔn)類都包含一個(gè) 范圍 方法。此方法確定將在趨勢(shì)市度量標(biāo)準(zhǔn)范圍選擇菜單中提供的范圍。數(shù)組的密鑰確定應(yīng)在查詢中包含的時(shí)間間隔單位 (月，周，天等) 的數(shù)量，而值確定將放置在范圍選擇菜單中的「可讀的」文本。當(dāng)然，您無需定義任何范圍：

/**
 * Get the ranges available for the metric.
 *
 * @return array
 */
public function ranges()
{
    return [
        5 => '5 Days',
        10 => '10 Days',
        15 => '15 Days',
    ];
}

格式化趨勢(shì)值

有時(shí)，您可能希望添加一個(gè)前綴或后綴到趨勢(shì)值。為了實(shí)現(xiàn)這一點(diǎn)，您可以使用 prefix 和 suffix 方法：

return $this->countByDays($request, User::class)
            ->prefix(');

如果你的趨勢(shì) metric 是顯示一個(gè)貨幣值，您可以使用 dollars 和 euros 快捷方法快速在趨勢(shì)值前添加美元或歐元符號(hào)：

return $this->countByDays($request, User::class)
            ->dollars();

顯示當(dāng)前值

有時(shí)，您可能希望突出最新時(shí)間間隔的值。例如，在這個(gè)截圖中，在最后一天創(chuàng)建了 6 個(gè)用戶：

您可以使用 showLatestValue 方法完成這個(gè)：

return $this->countByDays($request, User::class)
            ->showLatestValue();

手動(dòng)構(gòu)建趨勢(shì)結(jié)果

如果您無法使用包含的查詢助手來構(gòu)建趨勢(shì)指標(biāo)，您可以手動(dòng)構(gòu)建 Laravel\Nova\Metrics\TrendResult 對(duì)象并從指標(biāo)的 calculate 方法中返回它：

return (new TrendResult)->trend([
    'July 1' => 100,
    'July 2' => 150,
    'July 3' => 200,
]);

分區(qū)指標(biāo)

分區(qū)指標(biāo)顯示值的餅圖。例如，分區(qū)指標(biāo)可能會(huì)顯示應(yīng)用程序提供的每個(gè)計(jì)費(fèi)計(jì)劃的用戶總數(shù)：

可以使用 nova：partition artisan 命令生成分區(qū)度量。默認(rèn)情況下，所有新指標(biāo)都將放在 app/nova/metrics 目錄中：

php artisan nova:partition UsersPerPlan

一旦生成了分區(qū)度量類，您就可以自定義了它。每個(gè)分區(qū)度量類包含一個(gè) calculate 方法。此方法應(yīng)返回一個(gè) laravel\nova\metrics\partitionResult 對(duì)象。別擔(dān)心，Nova 提供了各種各樣的助手，可以快速生成結(jié)果

在此示例中，我們正在使用 count 助手程序，它將自動(dòng)執(zhí)行針對(duì)指定的 eloquent 模型的 count 查詢，并檢索屬于指定的每個(gè)不同值的模型數(shù)量「group by」列：

<?php

namespace App\Nova\Metrics;

use App\User;
use Illuminate\Http\Request;
use Laravel\Nova\Metrics\Partition;

class UsersPerPlan extends Partition
{
    /**
     * 計(jì)算度量標(biāo)準(zhǔn)的值。
     *
     * @param  \Illuminate\Http\Request  $request
     * @return mixed
     */
    public function calculate(Request $request)
    {
        return $this->count($request, User::class, 'stripe_plan');
    }

    /**
     * 獲取度量標(biāo)準(zhǔn)的URI鍵。
     *
     * @return string
     */
    public function uriKey()
    {
        return 'users-by-plan';
    }
}

分區(qū)查詢類型

分區(qū)度量不只附帶 count 幫助器。在構(gòu)建指標(biāo)時(shí)，您還可以使用各種其他聚合函數(shù)。

平均值

average 方法可用于計(jì)算不同組中給定列的平均值。例如，以下對(duì) average 方法的調(diào)用將顯示一個(gè)餅形圖，其中包含公司每個(gè)部門的平均訂單價(jià)格：

return $this->average($request, Order::class, 'price', 'department');

求和

sum 方法可用于計(jì)算不同組中給定列的總和。例如，以下對(duì) sum 方法的調(diào)用將顯示一個(gè)餅圖，其中包含公司每個(gè)部門的所有訂單價(jià)格的總和：

return $this->sum($request, Order::class, 'price', 'department');

最大值

max 方法可用于計(jì)算不同組中給定列的最大值。例如，以下對(duì) max 方法的調(diào)用將顯示一個(gè)餅圖，其中包含公司每個(gè)部門的最高訂單價(jià)格：

return $this->max($request, Order::class, 'price', 'department');

Min

min 方法可用于計(jì)算不同組內(nèi)給定列的最小值。例如下面的 min 方法將顯示一個(gè)餅圖，其中包含公司每個(gè)部門的最低訂單價(jià)格：

return $this->min($request, Order::class, 'price', 'department');

自定義分區(qū)標(biāo)簽

通常，將分區(qū) metrics 指標(biāo)分組的列值將是最簡(jiǎn)單的鍵，而不是 “友好” 的東西?；蛘撸绻@示布爾值列分組的分區(qū) metric，Nova 會(huì)將您的組標(biāo)簽顯示為 “0” 和 "1"。因此，Nova 允許您提供一個(gè) Closure 將標(biāo)簽格式化為更具有可讀性的內(nèi)容：

/**
 * 計(jì)算 metric 的值。
 *
 * @param  \Illuminate\Http\Request  $request
 * @return mixed
 */
public function calculate(Request $request)
{
    return $this->count($request, User::class, 'stripe_plan')
            ->label(function ($value) {
                switch ($value) {
                    case null:
                        return 'None';
                    default:
                        return ucfirst($value);
                }
            });
}

手動(dòng)生成分區(qū)結(jié)果

如果您無法使用內(nèi)置的查詢助手構(gòu)建你的分區(qū) metric，您可以使用 result 方法手動(dòng)為 metric 提供最終值：

return $this->result([
    'Group 1' => 100,
    'Group 2' => 200,
    'Group 3' => 300,
]);

緩存

有時(shí) metric 值的計(jì)算可能會(huì)很慢且成本很高。因此，所有 Nova metrics 都包含一個(gè) cacheFor 方法，該方法允許您指定 metric 結(jié)果的緩存時(shí)長：

/**
 * 指定 metric 應(yīng)緩存多少分鐘。
 *
 * @return  \DateTimeInterface|\DateInterval|float|int
 */
public function cacheFor()
{
    return now()->addMinutes(5);
}