Laravel Trend

https://github.com/flowframe/laravel-trend
Admin
A fluent Laravel package that easily generates model trends and charts with support for aggregating...
Tokens:19,596
Snippets:148
Trust Score:6.8
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### Start a Trend with Model or Query

Source: https://github.com/flowframe/laravel-trend/blob/master/README.md

Shows the two ways to start a trend: Trend::model() for a simple model and Trend::query() for a more specific Eloquent query with additional filters. Both examples count orders per day.

```php
// Model
Trend::model(Order::class)
    ->between(...)
    ->perDay()
    ->count();

// More specific order query
Trend::query(
    Order::query()
        ->hasBeenPaid()
        ->hasBeenShipped()
)
    ->between(...)
    ->perDay()
    ->count();
```

--------------------------------

### Install Laravel Trend via Composer

Source: https://github.com/flowframe/laravel-trend/blob/master/README.md

Install the package using Composer. Run this command in your project root.

```bash
composer require flowframe/laravel-trend
```

--------------------------------

### Example: average with between and perYear

Source: https://github.com/flowframe/laravel-trend

Example using the average shorthand with a query builder, between() with named arguments, and perYear(). Returns a Collection of TrendValue objects.

```php
$perDay = Trend::query(User::where('name', 'like', 'a%'))
    ->between(start: now()->startOfYear()->subYears(10), end: now()->endOfYear())
    ->perYear()
    ->average('weight');
```

--------------------------------

### dateColumn usage example

Source: https://github.com/flowframe/laravel-trend

Shows how to set a custom date column 'paid_at' for a Trend query on Order models, bucketing by day between the start of the month and now.

```php
$trend = Trend::model(Order::class)
    ->dateColumn('paid_at')
    ->between(start: now()->startOfMonth(), end: now())
    ->perDay()
    ->count();
```

--------------------------------

### Example: per-hour count with error handling

Source: https://github.com/flowframe/laravel-trend

Example using the count shorthand with perHour() inside a try-catch block. Catches \Error and logs a warning with the exception.

```php
try {
    $hourly = Trend::model(Visit::class)
        ->between(now()->startOfDay(), now())
        ->perHour()
        ->count();
} catch (\Error $e) {
    Log::warning('Trend aggregation failed', ['exception' => $e]);
}
```

--------------------------------

### aggregate usage example with sum

Source: https://github.com/flowframe/laravel-trend

Shows how to use the aggregate method with a custom column 'total' and 'sum' aggregate, then sum the results.

```php
$rows = Trend::model(Order::class)
    ->between(now()->subYear(), now())
    ->perMonth()
    ->aggregate('total', 'sum');

$total = $rows->sum('aggregate');
```

--------------------------------

### between() usage example

Source: https://github.com/flowframe/laravel-trend

Creates a trend for the current month by passing named arguments `start` and `end` to `between()`. The range is inclusive and the returned `Trend` instance is fluent, so further chaining like `->perDay()` or `->sum()` can follow.

```php
$trend = Trend::model(Invoice::class)
    ->between(start: now()->startOfMonth(), end: now()->endOfMonth());
```

--------------------------------

### Direct usage example of MySqlAdapter::format()

Source: https://github.com/flowframe/laravel-trend

Shows how to consume an adapter directly, bypassing the internal selection. The format('created_at', 'day') call returns the SQL expression "date_format(created_at, '%Y-%m-%d')".

```php
use Flowframe\Trend\Adapters\MySqlAdapter;

$sqlExpr = (new MySqlAdapter())->format('created_at', 'day');
// "date_format(created_at, '%Y-%m-%d')"
```

--------------------------------

### perDay() usage example with zero-fill

Source: https://github.com/flowframe/laravel-trend

Builds a daily trend for the current week by chaining `between()`, `perDay()`, and `sum('total')`. Missing days are zero-filled in the result series.

```php
$daily = Trend::model(Order::class)
    ->between(start: now()->startOfWeek(), end: now())
    ->perDay()
    ->sum('total');
```

--------------------------------

### Example: reuse mapValuesToDates with a custom collection

Source: https://github.com/flowframe/laravel-trend

Example showing how to reuse mapValuesToDates with a manually built collection of raw rows. The method fills in zero-valued placeholders for missing dates and returns a sorted collection.

```php
$trend = Trend::model(Order::class)->between(now()->subMonth(), now())->perDay();

$raw = collect([
    (object) ['date' => now()->format('Y-m-d'), 'aggregate' => 5],
]);

$filled = $trend->mapValuesToDates($raw);
```

--------------------------------

### Constructing a Trend instance

Source: https://github.com/flowframe/laravel-trend

Creates a Trend instance directly from a query builder, then chains between() and perDay() to set the date range and interval, and finally calls count() to get the result.

```php
$trend = new Trend(User::query());
$result = $trend->between(now()->subDays(7), now())->perDay()->count();
```

--------------------------------

### between() method signature

Source: https://github.com/flowframe/laravel-trend

Declares the fluent `between($start, $end)` method that stores the inclusive range start and end. The parameters are untyped but a `Carbon\CarbonInterface` is expected; the values are used for the SQL `whereBetween` filter and to build the zero-filled `CarbonPeriod` placeholder series. Returns `self` for chaining.

```php
public function between($start, $end): self
```

--------------------------------

### Generate Trend with Model and Query

Source: https://github.com/flowframe/laravel-trend/blob/master/README.md

Shows two ways to generate trends: using Trend::model() for a model class and Trend::query() for an Eloquent query with filters. The first counts users per month for the current year, the second averages user weight per year over 11 years for names starting with 'a'.

```php
// Totals per month
$trend = Trend::model(User::class)
    ->between(
        start: now()->startOfYear(),
        end: now()->endOfYear(),
    )
    ->perMonth()
    ->count();

// Average user weight where name starts with a over a span of 11 years, results are grouped per year
$trend = Trend::query(User::where('name', 'like', 'a%'))
    ->between(
        start: now()->startOfYear()->subYears(10),
        end: now()->endOfYear(),
    )
    ->perYear()
    ->average('weight');
```

--------------------------------

### Constructing TrendValue directly / defensive access

Source: https://github.com/flowframe/laravel-trend

Shows how to manually create a TrendValue instance, useful for tests or custom placeholder logic. The example also demonstrates a defensive check for when the aggregate value is falsy (e.g., 0 for empty buckets).

```php
$value = new TrendValue(
    date: '2024-06-01',
    aggregate: 42,
);

if (! $value->aggregate) {
    // bucket had no matching rows (aggregate === 0)
}
```

--------------------------------

### Specify Custom Date Column

Source: https://github.com/flowframe/laravel-trend/blob/master/README.md

Use the dateColumn() method to specify a custom date column when the model does not use the default created_at column. This example counts orders per day using a custom_date_column.

```php
Trend::model(Order::class)
    ->dateColumn('custom_date_column')
    ->between(...)
    ->perDay()
    ->count();
```

--------------------------------

### between($start, $end): Trend

Source: https://github.com/flowframe/laravel-trend

Sets the inclusive start and end of the trend range. These values are used for the SQL whereBetween filter and to build the zero-filled CarbonPeriod placeholder series.

```APIDOC
## between($start, $end): Trend

### Description
Sets the inclusive start and end of the trend range. These values are used for the SQL whereBetween filter and to build the zero-filled CarbonPeriod placeholder series.

### Method
between

### Endpoint
between($start, $end)

### Parameters
#### Path Parameters
- **$start** (mixed) - Required - Inclusive start of the trend range (a Carbon\CarbonInterface is expected)
- **$end** (mixed) - Required - Inclusive end of the trend range (a Carbon\CarbonInterface is expected)

### Response
#### Success Response
- **Returns** (self) - Fluent

### Request Example
```php
$trend = Trend::model(Invoice::class)
    ->between(start: now()->startOfMonth(), end: now()->endOfMonth());
```
```

--------------------------------

### dateAlias usage example

Source: https://github.com/flowframe/laravel-trend

Shows how to set a custom alias 'bucket_date' for the date column in a Trend query. The comment notes that $row->date is the bucket label (TrendValue::$date).

```php
$rows = Trend::model(Order::class)
    ->dateAlias('bucket_date')
    ->between(now()->subMonth(), now())
    ->perDay()
    ->count();

foreach ($rows as $row) {
    // $row->date is the bucket label (TrendValue::$date)
}
```

--------------------------------

### Trend::model(string $model): Trend

Source: https://github.com/flowframe/laravel-trend

Starts a new Trend instance from an Eloquent model class name. This is the entry point for generating trend data from a model.

```APIDOC
## Trend::model(string $model): Trend

### Description
Starts a new Trend instance from an Eloquent model class name. This is the entry point for generating trend data from a model.

### Method
model

### Parameters
- **$model** (string) - Required - The Eloquent model class name.

### Returns
- **Trend** - A new Trend instance.
```

--------------------------------

### Trend::query(Builder $builder): Trend

Source: https://github.com/flowframe/laravel-trend

Starts a new Trend instance from an existing Eloquent query builder. This is the entry point for generating trend data from a custom query.

```APIDOC
## Trend::query(Builder $builder): Trend

### Description
Starts a new Trend instance from an existing Eloquent query builder. This is the entry point for generating trend data from a custom query.

### Method
query

### Parameters
- **$builder** (Illuminate\Database\Eloquent\Builder) - Required - The Eloquent query builder to start from.

### Returns
- **Trend** - A new Trend instance.
```

--------------------------------

### Basic usage - iterate a trend result

Source: https://github.com/flowframe/laravel-trend

Iterate over a collection of TrendValue instances returned by a Trend aggregate method. The example uses `count()` and accesses the public `$date` and `$aggregate` properties. The `$rows->sum('aggregate')` call sums the aggregate values using Collection's sum method.

```php
use Flowframe\Trend\Trend;
use Flowframe\Trend\TrendValue;

$rows = Trend::model(Order::class)
    ->between(start: now()->startOfMonth(), end: now())
    ->perDay()
    ->count();

/** @var TrendValue $row */
foreach ($rows as $row) {
    echo $row->date . ': ' . $row->aggregate . PHP_EOL;
}

$total = $rows->sum('aggregate'); // Collection::sum over the public property
```

--------------------------------

### Interval shorthand method signatures

Source: https://github.com/flowframe/laravel-trend

Lists the six fluent shorthand methods that delegate to `interval()` with the corresponding raw key: `perMinute()` sets `minute`, `perHour()` sets `hour`, `perDay()` sets `day`, `perWeek()` sets `week`, `perMonth()` sets `month`, and `perYear()` sets `year`. Each returns `self` for chaining.

```php
public function perMinute(): self // src/Trend.php:55
public function perHour(): self   // src/Trend.php:60
public function perDay(): self    // src/Trend.php:65
public function perWeek(): self   // src/Trend.php:70
public function perMonth(): self  // src/Trend.php:75
public function perYear(): self   // src/Trend.php:80
```

--------------------------------

### interval() method signature

Source: https://github.com/flowframe/laravel-trend

Declares the fluent `interval(string $interval)` method that sets the raw interval key. Accepted values are `minute`, `hour`, `day`, `week`, `month`, or `year`. Unknown values are not validated here and will surface later as `\Error('Invalid interval.')` from the adapters or the Carbon date-format matcher. Prefer the `per*()` shorthand. Returns `self`.

```php
public function interval(string $interval): self
```

--------------------------------

### Interval shorthands (fluent)

Source: https://github.com/flowframe/laravel-trend

Fluent shorthand methods that delegate to interval() with a specific interval key. Each sets the interval for the trend query.

```APIDOC
## Interval shorthands (fluent)

### Description
Fluent shorthand methods that delegate to interval() with a specific interval key. Each sets the interval for the trend query.

### Methods
- perMinute() - Sets interval to 'minute'
- perHour() - Sets interval to 'hour'
- perDay() - Sets interval to 'day'
- perWeek() - Sets interval to 'week'
- perMonth() - Sets interval to 'month'
- perYear() - Sets interval to 'year'

### Response
#### Success Response
- **Returns** (self) - Fluent

### Request Example
```php
$daily = Trend::model(Order::class)
    ->between(start: now()->startOfWeek(), end: now())
    ->perDay()
    ->sum('total');
```
```

--------------------------------

### AbstractAdapter class definition

Source: https://github.com/flowframe/laravel-trend

Defines the abstract contract for all dialect adapters. Concrete classes must implement format(string $column, string $interval): string, which returns a raw SQL expression for bucketing the column by the interval.

```php
namespace Flowframe\Trend\Adapters;

abstract class AbstractAdapter
{
    abstract public function format(string $column, string $interval): string;
}
```

--------------------------------

### dateColumn method signature

Source: https://github.com/flowframe/laravel-trend

Declares the dateColumn method that overrides the default 'created_at' date column. Returns self for fluent chaining.

```php
public function dateColumn(string $column): self
```

--------------------------------

### SqliteAdapter format() implementation

Source: https://github.com/flowframe/laravel-trend

Defines the SQLite adapter's format() method, which maps interval strings to SQLite strftime format strings and returns a strftime expression. Throws \Error('Invalid interval.') for any interval other than minute, hour, day, week, month, or year.

```php
namespace Flowframe\Trend\Adapters;

use Error;

class SqliteAdapter extends AbstractAdapter
{
    public function format(string $column, string $interval): string
    {
        $format = match ($interval) {
            'minute' => '%Y-%m-%d %H:%M:00',
            'hour' => '%Y-%m-%d %H:00',
            'day' => '%Y-%m-%d',
            'week' => '%Y-%W',
            'month' => '%Y-%m',
            'year' => '%Y',
            default => throw new Error('Invalid interval.'),
        };

        return "strftime('{$format}', {$column})";
    }
}

```

--------------------------------

### Trend::query() error-aware usage with try/catch

Source: https://github.com/flowframe/laravel-trend

Defensive usage wrapping the terminal count() call in try/catch. aggregate() throws \Error for unsupported database drivers or invalid intervals; catch and report the error.

```php
try {
    $rows = Trend::query(User::query())
        ->between(now()->subMonth(), now())
        ->perDay()
        ->count();
} catch (\Error $e) {
    // 'Unsupported database driver.' or 'Invalid interval.'
    report($e);
}
```

--------------------------------

### Aggregate shorthand method signatures

Source: https://github.com/flowframe/laravel-trend

Method signatures for average, min, max, sum, and count shorthands in src/Trend.php. Each is a thin wrapper over aggregate() with the corresponding SQL aggregate (avg, min, max, sum, count). count() has an optional $column parameter defaulting to '*'.

```php
public function average(string $column): Collection // src/Trend.php:115
public function min(string $column): Collection     // src/Trend.php:120
public function max(string $column): Collection     // src/Trend.php:125
public function sum(string $column): Collection     // src/Trend.php:130
public function count(string $column = '*'): Collection // src/Trend.php:135
```

--------------------------------

### PgsqlAdapter format method

Source: https://github.com/flowframe/laravel-trend

Defines the PgsqlAdapter class that formats a column and interval into a PostgreSQL to_char expression with double-quoted column identifiers. Supports intervals minute, hour, day, week, month, and year, and throws an Error for invalid intervals.

```php
namespace Flowframe\Trend\Adapters;

use Error;

class PgsqlAdapter extends AbstractAdapter
{
    public function format(string $column, string $interval): string
    {
        $format = match ($interval) {
            'minute' => 'YYYY-MM-DD HH24:MI:00',
            'hour' => 'YYYY-MM-DD HH24:00:00',
            'day' => 'YYYY-MM-DD',
            'week' => 'IYYY-IW',
            'month' => 'YYYY-MM',
            'year' => 'YYYY',
            default => throw new Error('Invalid interval.'),
        };

        return "to_char(\"{$column}\", '{$format}')";
    }
}
```

--------------------------------

### Import the Trend class

Source: https://github.com/flowframe/laravel-trend

Imports the main Trend class from the Flowframe\Trend namespace.

```php
use Flowframe\Trend\Trend;
```

--------------------------------

### Trend::model() usage with User model

Source: https://github.com/flowframe/laravel-trend

Creates a Trend from the User model using Trend::model(), then applies between, perMonth, and count. The model is consumed as-is; use Trend::query() for extra filters.

```php
$trend = Trend::model(User::class)
    ->between(start: now()->startOfYear(), end: now()->endOfYear())
    ->perMonth()
    ->count();
```

--------------------------------

### Trend::query() basic usage with filters

Source: https://github.com/flowframe/laravel-trend

Creates a Trend from an Eloquent builder with additional scopes (hasBeenPaid, hasBeenShipped), then applies between, perDay, and count.

```php
$trend = Trend::query(
    Order::query()
        ->hasBeenPaid()
        ->hasBeenShipped()
)
    ->between(start: now()->startOfMonth(), end: now())
    ->perDay()
    ->count();
```

--------------------------------

### aggregate SQL query

Source: https://github.com/flowframe/laravel-trend

Shows the SQL query executed by the aggregate method on the base builder, selecting the formatted date and aggregate value, filtering by date range, and grouping by the date alias.

```php
selectRaw("
    {$this->getSqlDate()} as {$this->dateAlias},
    {$aggregate}({$column}) as aggregate
")
->whereBetween($this->dateColumn, [$this->start, $this->end])
->groupBy($this->dateAlias)
->orderBy($this->dateAlias)
->get();
```

--------------------------------

### Import TrendServiceProvider

Source: https://github.com/flowframe/laravel-trend

Import the service provider class for use in application code or tests.

```php
use Flowframe\Trend\TrendServiceProvider;
```

--------------------------------

### MySqlAdapter format method

Source: https://github.com/flowframe/laravel-trend

Defines the MySqlAdapter class that formats a column and interval into a MySQL DATE_FORMAT expression. Supports intervals minute, hour, day, week, month, and year, and throws an Error for invalid intervals.

```php
namespace Flowframe\Trend\Adapters;

use Error;

class MySqlAdapter extends AbstractAdapter
{
    public function format(string $column, string $interval): string
    {
        $format = match ($interval) {
            'minute' => '%Y-%m-%d %H:%i:00',
            'hour' => '%Y-%m-%d %H:00',
            'day' => '%Y-%m-%d',
            'week' => '%Y-%u',
            'month' => '%Y-%m',
            'year' => '%Y',
            default => throw new Error('Invalid interval.'),
        };

        return "date_format({$column}, '{$format}')";
    }
}
```

--------------------------------

### Trend::query() method signature

Source: https://github.com/flowframe/laravel-trend

Static method signature for Trend::query(). Accepts an Eloquent Builder and returns a new Trend instance.

```php
public static function query(Builder $builder): self
```

--------------------------------

### __construct(Builder $builder)

Source: https://github.com/flowframe/laravel-trend

Constructs a Trend instance directly from an Eloquent builder. Prefer the static factories Trend::query() or Trend::model().

```APIDOC
## __construct(Builder $builder)

### Description
Constructs a Trend instance directly from an Eloquent builder. Prefer the static factories Trend::query() / Trend::model().

### Method
Constructor

### Parameters
- **$builder** (Illuminate\Database\Eloquent\Builder) - Required - Eloquent query builder the aggregate query runs against

### Returns
Trend (new instance)

### Example
```php
$trend = new Trend(User::query());
$result = $trend->between(now()->subDays(7), now())->perDay()->count();
```
```

--------------------------------

### Import TrendValue class

Source: https://github.com/flowframe/laravel-trend

Import the TrendValue class for use in your PHP code.

```php
use Flowframe\Trend\TrendValue;
```

--------------------------------

### Composer extra configuration for auto-discovery

Source: https://github.com/flowframe/laravel-trend

Declares the service provider and a Trend facade alias in composer.json for Laravel package discovery. The facade class does not exist in the repository, so resolving the alias fails; use the Trend class directly.

```json
"extra": {
    "laravel": {
        "providers": [
            "Flowframe\\Trend\\TrendServiceProvider"
        ],
        "aliases": {
            "Trend": "Flowframe\\Trend\\TrendFacade"
        }
    }
}
```

--------------------------------

### AbstractAdapter contract

Source: https://github.com/flowframe/laravel-trend

Abstract adapter class that must implement format(string $column, string $interval): string. Concrete dialects include MySqlAdapter, PgsqlAdapter, and SqliteAdapter.

```php
abstract class AbstractAdapter
{
    abstract public function format(string $column, string $interval): string;
}
```

--------------------------------

### Trend constructor signature

Source: https://github.com/flowframe/laravel-trend

The constructor signature for the Trend class. It accepts an Eloquent query builder. Prefer the static factories Trend::query() or Trend::model() instead of using this directly.

```php
public function __construct(public Builder $builder)
```

--------------------------------

### aggregate method signature

Source: https://github.com/flowframe/laravel-trend

Declares the aggregate method that executes the core aggregation engine. Returns a Collection of TrendValue objects.

```php
public function aggregate(string $column, string $aggregate): Collection
```

--------------------------------

### dateAlias method signature

Source: https://github.com/flowframe/laravel-trend

Declares the dateAlias method that changes the SQL alias / result key for the formatted date column. Returns self for fluent chaining.

```php
public function dateAlias(string $alias): self
```

--------------------------------

### Trend class signature

Source: https://github.com/flowframe/laravel-trend

Shows the public properties and constructor of the Trend class. The $interval property accepts one of 'minute', 'hour', 'day', 'week', 'month', or 'year'. The $dateColumn defaults to 'created_at' and $dateAlias to 'date'. The constructor promotes the $builder parameter.

```php
class Trend
{
    public string $interval;

    public CarbonInterface $start;

    public CarbonInterface $end;

    public string $dateColumn = 'created_at';

    public string $dateAlias = 'date';

    public function __construct(public Builder $builder)
    {
    }
    // ... methods below
}
```

--------------------------------

### interval(string $interval): Trend

Source: https://github.com/flowframe/laravel-trend

Raw setter for the interval. Unknown values are not validated here; they surface later as \Error('Invalid interval.') from the adapters or the Carbon date-format matcher.

```APIDOC
## interval(string $interval): Trend

### Description
Raw setter for the interval. Unknown values are not validated here; they surface later as \Error('Invalid interval.') from the adapters or the Carbon date-format matcher.

### Method
interval

### Endpoint
interval($interval)

### Parameters
#### Path Parameters
- **$interval** (string) - Required - Raw interval key: minute, hour, day, week, month, or year

### Response
#### Success Response
- **Returns** (self) - Fluent
```

--------------------------------

### Register provider in Orchestra Testbench

Source: https://github.com/flowframe/laravel-trend

Explicitly registers the service provider in a test suite using getPackageProviders. Required for Orchestra Testbench tests; normal Laravel apps use auto-discovery.

```php
protected function getPackageProviders($app)
{
    return [
        \Flowframe\Trend\TrendServiceProvider::class,
    ];
}
```

--------------------------------

### Unsupported database driver match expression

Source: https://github.com/flowframe/laravel-trend

Thrown in Trend::getSqlDate() when the connection driver name is not mysql, mariadb, sqlite, or pgsql. The match expression maps supported drivers to adapters and throws a built-in \Error with the message 'Unsupported database driver.' for any other driver.

```php
$adapter = match ($this->builder->getConnection()->getDriverName()) {
    'mysql', 'mariadb' => new MySqlAdapter(),
    'sqlite' => new SqliteAdapter(),
    'pgsql' => new PgsqlAdapter(),
    default => throw new Error('Unsupported database driver.'),
};
```

--------------------------------

### Trend::model() method signature

Source: https://github.com/flowframe/laravel-trend

Static method signature for Trend::model(). Accepts a fully-qualified Eloquent model class name and returns a new Trend instance.

```php
public static function model(string $model): self
```

--------------------------------

### TrendServiceProvider

Source: https://github.com/flowframe/laravel-trend

Service provider for package registration. Registered via Laravel package discovery.

```APIDOC
## TrendServiceProvider

### Description
Service provider for package registration. Registered via Laravel package discovery.

### Registration
- Registered via Laravel package discovery.
```

--------------------------------

### aggregate(string $column, string $aggregate): Collection

Source: https://github.com/flowframe/laravel-trend

The core engine. Executes over the builder's base query, grouping by the date alias and ordering by it, then returns real rows merged with zero-filled buckets for the full period. Returns a Collection of TrendValue objects.

```APIDOC
## aggregate(string $column, string $aggregate): Collection

### Description
The core engine. Executes over `$this->builder->toBase()`:

```php
selectRaw("
    {$this->getSqlDate()} as {$this->dateAlias},
    {$aggregate}({$column}) as aggregate
")
->whereBetween($this->dateColumn, [$this->start, $this->end])
->groupBy($this->dateAlias)
->orderBy($this->dateAlias)
->get();
```

then returns `$this->mapValuesToDates($values)` — i.e. real rows merged with zero-filled buckets for the full `start`–`end` period.

### Method
`aggregate`

### Parameters
- `$column` (string) - Required - Column to aggregate, e.g. `'total'` or `'*'`
- `$aggregate` (string) - Required - SQL aggregate function name: e.g. `count`, `sum`, `avg`, `min`, `max`

### Returns
`Illuminate\Support\Collection` of `Flowframe\Trend\TrendValue` (`date` as formatted string, `aggregate` as the raw SQL aggregate value; `0` for empty buckets)

### Errors
- Throws `\Error` with message `'Unsupported database driver.'` when the connection driver is not `mysql`/`mariadb`/`sqlite`/`pgsql`
- Throws `\Error` with message `'Invalid interval.'` when the interval is not `minute`/`hour`/`day`/`week`/`month`/`year`

### Request Example
```php
$rows = Trend::model(Order::class)
    ->between(now()->subYear(), now())
    ->perMonth()
    ->aggregate('total', 'sum');

$total = $rows->sum('aggregate');
```
```

--------------------------------

### TrendServiceProvider class signature

Source: https://github.com/flowframe/laravel-trend

The provider extends PackageServiceProvider and sets the package name to 'laravel-trend'. It registers no migrations, views, config files, translations, or commands.

```php
class TrendServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package->name('laravel-trend');
    }
}
```

--------------------------------

### new TrendValue($date, $aggregate)

Source: https://github.com/flowframe/laravel-trend

Constructor for the TrendValue value object. Creates a new instance representing one time bucket of a trend result, with a date label and an aggregated value.

```APIDOC
## Constructor

### Description
Creates a new TrendValue instance with the given date and aggregate value.

### Parameters
- **$date** (string) - Required - Bucket label in the interval-specific format (e.g., 'Y-m-d' for day, 'Y-m' for month).
- **$aggregate** (mixed) - Required - Aggregated value for the bucket; 0 for empty buckets where no rows matched.

### Example
```php
$value = new TrendValue(
    date: '2024-06-01',
    aggregate: 42,
);
```
```

--------------------------------

### mapValuesToDates method signature

Source: https://github.com/flowframe/laravel-trend

Public method signature for mapValuesToDates(Collection $values): Collection. Takes raw rows from the aggregate query and returns a Collection of TrendValue objects.

```php
public function mapValuesToDates(Collection $values): Collection
```

--------------------------------

### dateAlias(string $alias): Trend

Source: https://github.com/flowframe/laravel-trend

Changes the key under which each bucket's date appears. The SQL query aliases the formatted date to this value and mapValuesToDates() reads it to build TrendValue::date. Returns self for fluent chaining.

```APIDOC
## dateAlias(string $alias): Trend

### Description
Changes the key under which each bucket's date appears. The SQL query aliases the formatted date to this value (`... as {$this->dateAlias}`) and `mapValuesToDates()` reads `$value->{$this->dateAlias}` to build `TrendValue::date`.

### Method
`dateAlias`

### Parameters
- `$alias` (string) - Required - SQL alias / result key for the formatted date column

### Returns
`self` (fluent)

### Request Example
```php
$rows = Trend::model(Order::class)
    ->dateAlias('bucket_date')
    ->between(now()->subMonth(), now())
    ->perDay()
    ->count();

foreach ($rows as $row) {
    // $row->date is the bucket label (TrendValue::$date)
}
```
```

--------------------------------

### min(string $column): Collection

Source: https://github.com/flowframe/laravel-trend

Computes the minimum value of the given column over the trend intervals. Returns a collection of TrendValue objects.

```APIDOC
## min(string $column): Collection

### Description
Computes the minimum value of the given column over the trend intervals. Returns a collection of TrendValue objects.

### Method
`min`

### Parameters
- **$column** (string) - Required - The column to find the minimum of.

### Returns
`Illuminate\Support\Collection` of `TrendValue` objects.
```

--------------------------------

### average(string $column): Collection

Source: https://github.com/flowframe/laravel-trend

Computes the average of the given column over the trend intervals. Returns a collection of TrendValue objects.

```APIDOC
## average(string $column): Collection

### Description
Computes the average of the given column over the trend intervals. Returns a collection of TrendValue objects.

### Method
`average`

### Parameters
- **$column** (string) - Required - The column to average.

### Returns
`Illuminate\Support\Collection` of `TrendValue` objects.

### Example
```php
$perDay = Trend::query(User::where('name', 'like', 'a%'))
    ->between(start: now()->startOfYear()->subYears(10), end: now()->endOfYear())
    ->perYear()
    ->average('weight');
```
```

--------------------------------

### sum(string $column): Collection

Source: https://github.com/flowframe/laravel-trend

Computes the sum of the given column over the trend intervals. Returns a collection of TrendValue objects.

```APIDOC
## sum(string $column): Collection

### Description
Computes the sum of the given column over the trend intervals. Returns a collection of TrendValue objects.

### Method
`sum`

### Parameters
- **$column** (string) - Required - The column to sum.

### Returns
`Illuminate\Support\Collection` of `TrendValue` objects.
```

--------------------------------

### Catching Trend errors in consumer code

Source: https://github.com/flowframe/laravel-trend

Wrap terminal aggregate calls in a try/catch block to handle the two possible \Error messages. Since the package throws the generic \Error type, branch on the exact message text rather than a package-specific exception class.

```php
use Flowframe\Trend\Trend;
use Error;

try {
    $rows = Trend::model(Order::class)
        ->between(start: now()->startOfMonth(), end: now())
        ->perDay()
        ->count();
} catch (Error $e) {
    match ($e->getMessage()) {
        'Unsupported database driver.' => report('Trend: unsupported database driver'),
        'Invalid interval.' => report('Trend: invalid interval'),
        default => throw $e,
    };
}
```

--------------------------------

### dateColumn(string $column): Trend

Source: https://github.com/flowframe/laravel-trend

Overrides the default 'created_at' date column for models with custom timestamp columns or when analyzing a different date field. Returns self for fluent chaining.

```APIDOC
## dateColumn(string $column): Trend

### Description
Overrides the default `created_at` date column, for models with custom timestamp columns or when analyzing a different date field.

### Method
`dateColumn`

### Parameters
- `$column` (string) - Required - Database column holding the date to bucket

### Returns
`self` (fluent)

### Request Example
```php
$trend = Trend::model(Order::class)
    ->dateColumn('paid_at')
    ->between(start: now()->startOfMonth(), end: now())
    ->perDay()
    ->count();
```
```

--------------------------------

### TrendValue properties: $date and $aggregate

Source: https://github.com/flowframe/laravel-trend

Public read/write properties of the TrendValue object. $date holds the bucket label, $aggregate holds the aggregated value.

```APIDOC
## Properties

### Description
Both parameters are promoted to public read/write properties.

### Properties
- **$date** (string) - The bucket label in the interval-specific format.
- **$aggregate** (mixed) - The aggregated value for the bucket; 0 for empty buckets.

### Example
```php
$value = new TrendValue(date: '2024-06-01', aggregate: 42);
echo $value->date; // '2024-06-01'
echo $value->aggregate; // 42
```
```

--------------------------------

### max(string $column): Collection

Source: https://github.com/flowframe/laravel-trend

Computes the maximum value of the given column over the trend intervals. Returns a collection of TrendValue objects.

```APIDOC
## max(string $column): Collection

### Description
Computes the maximum value of the given column over the trend intervals. Returns a collection of TrendValue objects.

### Method
`max`

### Parameters
- **$column** (string) - Required - The column to find the maximum of.

### Returns
`Illuminate\Support\Collection` of `TrendValue` objects.
```

--------------------------------

### count(string $column = '*'): Collection

Source: https://github.com/flowframe/laravel-trend

Counts the number of rows (or non-null values of the given column) over the trend intervals. Returns a collection of TrendValue objects.

```APIDOC
## count(string $column = '*'): Collection

### Description
Counts the number of rows (or non-null values of the given column) over the trend intervals. Returns a collection of TrendValue objects.

### Method
`count`

### Parameters
- **$column** (string) - Optional - The column to count. Defaults to `'*'` (count all rows).

### Returns
`Illuminate\Support\Collection` of `TrendValue` objects.

### Example
```php
try {
    $hourly = Trend::model(Visit::class)
        ->between(now()->startOfDay(), now())
        ->perHour()
        ->count();
} catch (\Error $e) {
    Log::warning('Trend aggregation failed', ['exception' => $e]);
}
```
```

--------------------------------

### mapValuesToDates(Collection $values): Collection

Source: https://github.com/flowframe/laravel-trend

Maps raw aggregate rows to TrendValue objects and fills in zero-value placeholders for each interval in the range. Returns a collection of TrendValue objects ordered by date.

```APIDOC
## mapValuesToDates(Collection $values): Collection

### Description
Maps raw aggregate rows to TrendValue objects and fills in zero-value placeholders for each interval in the range. Returns a collection of TrendValue objects ordered by date.

### Method
`mapValuesToDates`

### Parameters
- **$values** (`Illuminate\Support\Collection`) - Required - Raw rows from the aggregate query (each with the date alias and `aggregate` keys).

### Returns
`Illuminate\Support\Collection` of `TrendValue` objects.

### Example
```php
$trend = Trend::model(Order::class)->between(now()->subMonth(), now())->perDay();

$raw = collect([
    (object) ['date' => now()->format('Y-m-d'), 'aggregate' => 5],
]);

$filled = $trend->mapValuesToDates($raw);
```
```

--------------------------------

### TrendValue

Source: https://github.com/flowframe/laravel-trend

Value object returned inside result collections. Contains a date and an aggregate value.

```APIDOC
## TrendValue

### Description
Value object returned inside result collections. Contains a date and an aggregate value.

### Properties
- **date** (string) - The date of the trend data point.
- **aggregate** (mixed) - The aggregate value for that date.
```

--------------------------------

### TrendValue class definition

Source: https://github.com/flowframe/laravel-trend

Defines the value object returned by aggregate methods. The constructor requires a string date and a mixed aggregate value; aggregate is 0 on placeholder buckets.

```php
class TrendValue
{
    public function __construct(
        public string $date,
        public mixed $aggregate,
    ) {
    }
}
```
Tokens:
Raw