Configuration

The package works with zero configuration. The published config/metrics.php in full:

use RoundlyConsulting\Metrics\Types\Trend\QueryExpressions\Mysql;
use RoundlyConsulting\Metrics\Types\Trend\QueryExpressions\Postgres;
use RoundlyConsulting\Metrics\Types\Trend\QueryExpressions\Sqlite;

return [
    'timezone' => env('METRICS_TIMEZONE'),

    'default_range' => 'ALL',
    'default_unit' => 'DAY',
    'precision' => 0,

    'cache' => [
        'enabled' => env('METRICS_CACHE_ENABLED', false),
        'store' => env('METRICS_CACHE_STORE'),
        'ttl' => env('METRICS_CACHE_TTL', 300),
        'prefix' => 'metrics',
    ],

    'partition' => [
        'other_label' => 'Other',
    ],

    'trend_drivers' => [
        'mysql' => Mysql::class,
        'mariadb' => Mysql::class,
        'pgsql' => Postgres::class,
        'sqlite' => Sqlite::class,
    ],
];

Every key

Key	Default	Env	Purpose
`timezone`	null	`METRICS_TIMEZONE`	Reporting timezone — ranges resolve in it and trend buckets are labelled in it; null or blank (not set) uses the app timezone. Override per metric with timezone(). Otherwise a string.
`default_range`	ALL	—	Period value (ALL, TODAY, 30, MTD, …) applied to every metric before setup(); an unknown value throws.
`default_unit`	DAY	—	Unit value (MINUTE … YEAR, exact case) used by trend metrics before setup(); an unknown value throws.
`precision`	0	—	Default rounding precision for every value — an integer (digit strings accepted).
`cache.enabled`	false	`METRICS_CACHE_ENABLED`	Master switch for result caching: true/false, 1/0, on/off or yes/no; anything else throws.
`cache.store`	null	`METRICS_CACHE_STORE`	Cache store name; null or blank (not set) uses the default store, otherwise a string.
`cache.ttl`	300	`METRICS_CACHE_TTL`	Seconds a cached result is remembered — a whole number from 1 to 31536000; digit strings from .env are accepted.
`cache.prefix`	metrics	—	Prefix for generated cache keys — a string; blank is not set, so metrics applies.
`partition.other_label`	Other	—	Translatable label of the rolled-up bucket when a partition is capped with limit() — a string; blank is not set, so Other applies.
`trend_drivers`	mysql, mariadb, pgsql, sqlite	—	Maps a database driver to the QueryExpression that builds trend date-grouping SQL; every entry must name a QueryExpression class.

Every key is read strictly and throws RoundlyConsulting\Metrics\Exceptions\InvalidConfigurationException naming it when present but unusable; a key that is not set — absent, null or blank (a host’s KEY=) — takes its default. default_range must be a Period value (ALL, TODAY, 30, …) and default_unit a Unit value (MINUTE … YEAR, exact case); precision must be an integer (digit strings accepted); timezone, cache.store, cache.prefix and partition.other_label must be strings; every trend_drivers entry must name a QueryExpression class. A typo is never silently ignored.

Defaults applied to every metric

default_range, default_unit and precision are read in the metric constructor, before setup() runs — so anything you set in setup() or through a fluent call overrides them:

// config/metrics.php
'default_range' => 'MTD',   // every metric defaults to month-to-date
'default_unit' => 'WEEK',   // trends bucket weekly unless told otherwise
'precision' => 2,           // values round to 2 decimals

Environment

The reporting timezone and the cache switches are env-driven:

METRICS_TIMEZONE=Europe/Bratislava
METRICS_CACHE_ENABLED=true
METRICS_CACHE_STORE=redis

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages