Quick Start ​

You can install the visualizations package via composer:

composer require settleup/visualizations

Metric Registration ​

Metrics are registered using the Route::metric() macro. This should be placed in your routes file:

Route::metric(RevenueMetric::class);

Usage ​

To create a new metric, define a class that extends the Metric class and implements the required methods. You can use the artisan command php artisan make:metric {name} to scaffold one. Below is a sample metric class:

<?php

namespace App\Metrics;

use Illuminate\Database\Query\Builder;
use Illuminate\Support\Facades\DB;
use SettleUp\Visualizations\Metrics\Abstracts\Metric;
use SettleUp\Visualizations\Metrics\Value;

class RevenueMetric extends Metric
{
    public function getValue(): Value
    {
        return Value::make('sum(orders.total)', 'revenue')
            ->header('Total Revenue');
    }

    public function getQuery(): Builder
    {
        return DB::table('orders');
    }
}

The getValue() method defines the scalar aggregate for the metric. The first argument to Value::make() is a raw SQL expression, and the second is the field alias used to retrieve the result. The header() call sets the human-readable label exposed in the schema.

Once registered, the following routes will be available. Using RevenueMetric as an example:

POST       metrics/revenues/data .......................... metrics.revenues.data
POST       metrics/revenues/schema ........................ metrics.revenues.schema

Schema ​

The schema endpoint returns the metric's structure for front-end consumption:

{
  "visualization_key": "metrics.revenues",
  "value": {
    "field": "revenue",
    "header": "Total Revenue",
    "meta": []
  },
  "floating_filters": []
}

Data ​

The data endpoint runs the aggregate query and returns the result:

{
  "value": 350.00
}

When the query returns no rows, value will be null.

Floating Filters ​

Metrics support floating filters, which allow the client to narrow the aggregate without the filter fields appearing in the metric definition itself. Override getFloatingFilters() to declare them:

use Illuminate\Support\Collection;
use SettleUp\Visualizations\FloatingFilters\DateRange;

public function getFloatingFilters(): Collection
{
    return collect([
        DateRange::make('orders.created_at', 'date_range')->header('Date Range'),
    ]);
}

Floating filters are passed from the client as filter_sets in the POST body sent to the data endpoint. See Floating Filters for full documentation.

Route Naming ​

Routes are derived automatically from the class name. A class named RevenueMetric produces:

The prefix defaults to metrics and can be overridden by implementing getRoutePrefix():

public function getRoutePrefix(): string
{
    return 'kpis';
}

Authorization ​

Metrics support the same gate-based authorization as other visualizations. Add the HasAuthorization trait and implement getPermissionName():

use SettleUp\Visualizations\Traits\HasAuthorization;

class RevenueMetric extends Metric
{
    use HasAuthorization;

    public function getPermissionName(): string
    {
        return 'view-revenue-metric';
    }
}

See Authorization for full documentation.