### Start Trend from Eloquent Query Builder

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Use `Trend::query()` with a pre-filtered Eloquent `Builder` instance to apply scopes, relationships, or constraints before generating trend data. This example shows daily counts for specific order types over the last 30 days, including zero-value placeholders.

```php
use Flowframe\Trend\Trend;
use App\Models\Order;

$trend = Trend::query(
    Order::query()
        ->hasBeenPaid()
        ->hasBeenShipped()
        ->where('channel', 'web')
)
    ->between(
        start: now()->subDays(30)->startOfDay(),
        end: now()->endOfDay(),
    )
    ->perDay()
    ->count();

// Returns daily counts for paid+shipped web orders over the last 30 days,
// with 0-filled placeholders for days with no matching records.
foreach ($trend as $value) {
    echo "{$value->date}: {$value->aggregate} orders\n";
}
// 2024-11-01: 34 orders
// 2024-11-02: 0 orders
// 2024-11-03: 41 orders
```

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

### Start Trend with Model

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

Initiate a trend analysis directly from a model class, specifying the interval and aggregate function. This is suitable when no additional query constraints are needed.

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

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

### Install Laravel Trend via Composer

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

Use this command to add the Laravel Trend package to your project dependencies.

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

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

### Start Trend with Query Builder

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

Begin a trend analysis using a custom Eloquent query builder instance. This allows for applying specific filters and scopes before generating the trend.

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

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

### Trend::query() — Start a trend from an Eloquent query builder

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Initiates a trend calculation starting from a pre-filtered Eloquent query builder instance. This allows for applying custom scopes, relationships, or constraints before the trend is calculated.

```APIDOC
## Trend::query()

### Description
Starts a new trend calculation using a pre-configured Eloquent query builder instance. This method is useful for applying specific filters or scopes before generating trend data.

### Method Signature
`Trend::query(Builder $query)`

### Parameters
* **query** (Builder) - Required - An instance of Eloquent's query builder with applied constraints.

### Usage Example
```php
use Flowframe\Trend\Trend;
use App\Models\Order;

$trend = Trend::query(
    Order::query()
        ->hasBeenPaid()
        ->hasBeenShipped()
        ->where('channel', 'web')
)
    ->between(
        start: now()->subDays(30)->startOfDay(),
        end: now()->endOfDay(),
    )
    ->perDay()
    ->count();
```
```

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

### Start Trend from Model Class

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Use `Trend::model()` to start a trend from an Eloquent model class. This method uses the model's default query. The results can be easily serialized for frontend charting libraries.

```php
use Flowframe\Trend\Trend;
use App\Models\Order;

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

// Returns a Collection of TrendValue objects:
// [
//   TrendValue { date: "2024-01", aggregate: 142 },
//   TrendValue { date: "2024-02", aggregate: 0   },
//   TrendValue { date: "2024-03", aggregate: 198 },
//   ...
// ]

// Serialize for a chart (e.g. Chart.js):
$labels = $trend->pluck('date');
$data   = $trend->pluck('aggregate');
```

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

### Set Date Range with `->between()`

Source: https://context7.com/flowframe/laravel-trend/llms.txt

The `->between()` method defines the start and end boundaries for the trend window. Both parameters should be `CarbonInterface` instances.

```php
use Flowframe\Trend\Trend;
use App\Models\User;
use Carbon\Carbon;

$trend = Trend::model(User::class)
    ->between(
        start: Carbon::parse('2023-01-01')->startOfDay(),
        end:   Carbon::parse('2023-12-31')->endOfDay(),
    )
    ->perMonth()
    ->count();
```

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

### Trend::model() — Start a trend from a model class

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Initiates a trend calculation starting from a given Eloquent model class. This method is suitable when you need to work with the full, unfiltered dataset of a model. It returns a `Trend` instance that can be further configured.

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

### Description
Starts a new trend calculation using an Eloquent model class. This provides a `Trend` instance based on the model's default query.

### Method Signature
`Trend::model(string $modelClass)`

### Parameters
* **modelClass** (string) - Required - The fully qualified class name of the Eloquent model.

### Usage Example
```php
use Flowframe\Trend\Trend;
use App\Models\Order;

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

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

### ->between() — Set the date range

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Defines the start and end boundaries for the time-series data aggregation. Both parameters must be instances that implement the `CarbonInterface`.

```APIDOC
## ->between()

### Description
Sets the date range (start and end) for which the trend data will be calculated. This method is crucial for defining the scope of your time-series analysis.

### Method Signature
`between(CarbonInterface $start, CarbonInterface $end)`

### Parameters
* **start** (CarbonInterface) - Required - The starting date and time of the trend window.
* **end** (CarbonInterface) - Required - The ending date and time of the trend window.

### Usage Example
```php
use Flowframe\Trend\Trend;
use App\Models\User;
use Carbon\Carbon;

$trend = Trend::model(User::class)
    ->between(
        start: Carbon::parse('2023-01-01')->startOfDay(),
        end:   Carbon::parse('2023-12-31')->endOfDay(),
    )
    ->perMonth()
    ->count();
```
```

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

### Generate Average Trend Per Year

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

Calculate the average 'weight' for users whose names start with 'a', over an 11-year period, grouped by year. This uses a query builder instance for filtering.

```php
// 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');
```

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

### Set Time Interval with Fluent Helpers

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Fluent helpers like `->perMinute()`, `->perHour()`, `->perDay()`, `->perWeek()`, `->perMonth()`, and `->perYear()` set the grouping interval for the trend. Each maps to a corresponding SQL date truncation format.

```php
use Flowframe\Trend\Trend;
use App\Models\PageView;

// Per-minute trend for the last hour (e.g., live dashboard)
$perMinute = Trend::model(PageView::class)
    ->between(now()->subHour(), now())
    ->perMinute()
    ->count();

// Per-hour trend for today
$perHour = Trend::model(PageView::class)
    ->between(now()->startOfDay(), now()->endOfDay())
    ->perHour()
    ->count();

// Per-week trend for the current year
$perWeek = Trend::model(PageView::class)
    ->between(now()->startOfYear(), now()->endOfYear())
    ->perWeek()
    ->count();

// Per-year trend over a decade
$perYear = Trend::model(PageView::class)
    ->between(now()->subYears(10)->startOfYear(), now()->endOfYear())
    ->perYear()
    ->count();
```

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

### ->perMinute(), ->perHour(), ->perDay(), ->perWeek(), ->perMonth(), ->perYear() — Set the time interval

Source: https://context7.com/flowframe/laravel-trend/llms.txt

These fluent helper methods specify the time interval for grouping the trend data. Each method corresponds to a specific SQL date truncation format, ensuring data is aggregated at the desired granularity.

```APIDOC
## Time Interval Methods

### Description
These methods set the granularity for aggregating trend data. Choose the interval that best suits your analysis needs, from minutes to years.

### Available Methods
* `perMinute()`
* `perHour()`
* `perDay()`
* `perWeek()`
* `perMonth()`
* `perYear()`

### Usage Examples
```php
use Flowframe\Trend\Trend;
use App\Models\PageView;

// Per-minute trend for the last hour
$perMinute = Trend::model(PageView::class)
    ->between(now()->subHour(), now())
    ->perMinute()
    ->count();

// Per-hour trend for today
$perHour = Trend::model(PageView::class)
    ->between(now()->startOfDay(), now()->endOfDay())
    ->perHour()
    ->count();

// Per-week trend for the current year
$perWeek = Trend::model(PageView::class)
    ->between(now()->startOfYear(), now()->endOfYear())
    ->perWeek()
    ->count();

// Per-year trend over a decade
$perYear = Trend::model(PageView::class)
    ->between(now()->subYears(10)->startOfYear(), now()->endOfYear())
    ->perYear()
    ->count();
```
```

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

### Minimum value of a column per interval

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Returns the minimum value of a column in each time period. This is useful for tracking minimum temperatures or prices over specific intervals.

```php
use Flowframe\Trend\Trend;
use App\Models\SensorReading;

$minTemp = Trend::model(SensorReading::class)
    ->between(now()->startOfWeek(), now()->endOfWeek())
    ->perDay()
    ->min('temperature');

```

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

### Count Records per Interval with `->count()`

Source: https://context7.com/flowframe/laravel-trend/llms.txt

The `->count()` method aggregates the number of records within each time period. It accepts an optional column name, defaulting to `*`.

```php
use Flowframe\Trend\Trend;
use App\Models\Order;

$trend = Trend::model(Order::class)
    ->between(now()->startOfMonth(), now()->endOfMonth())
    ->perDay()
    ->count();

// [
//   TrendValue { date: "2024-11-01", aggregate: 23 },
//   TrendValue { date: "2024-11-02", aggregate: 17 },
//   ...
// ]
```

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

### Generate Totals Trend Per Month

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

Calculate the total count of records for a model over a year, grouped by month. Ensure the `User` model and `Trend` class are imported.

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

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

### Maximum value of a column per interval

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Returns the maximum value of a column in each time period. This is useful for tracking maximum temperatures or prices over specific intervals.

```php
use Flowframe\Trend\Trend;
use App\Models\SensorReading;

$maxTemp = Trend::model(SensorReading::class)
    ->between(now()->startOfWeek(), now()->endOfWeek())
    ->perDay()
    ->max('temperature');

```

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

### Use a custom date column

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Overrides the default `created_at` column used for date filtering and grouping. Use this when your model tracks time via a different column, such as `shipped_at`.

```php
use Flowframe\Trend\Trend;
use App\Models\Order;

$trend = Trend::model(Order::class)
    ->dateColumn('shipped_at')        // group by shipped_at instead of created_at
    ->between(
        start: now()->startOfMonth(),
        end: now()->endOfMonth(),
    )
    ->perDay()
    ->count();

```

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

### Specify Custom Date Column

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

Analyze trends using a date column other than the default 'created_at'. This is useful when your model's relevant date information is stored in a different column.

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

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

### ->count() — Count records per interval

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Performs a count aggregation on the records within each specified time interval. This method can optionally accept a column name to count specific values, defaulting to counting all records (`*`).

```APIDOC
## ->count()

### Description
Aggregates the number of records within each time interval defined by the trend configuration. This is a common operation for understanding the volume of data over time.

### Method Signature
`count(string $column = '*')`

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

### Usage Example
```php
use Flowframe\Trend\Trend;
use App\Models\Order;

$trend = Trend::model(Order::class)
    ->between(now()->startOfMonth(), now()->endOfMonth())
    ->perDay()
    ->count();

// Result structure:
// [
//   TrendValue { date: "2024-11-01", aggregate: 23 },
//   TrendValue { date: "2024-11-02", aggregate: 17 },
//   ...
// ]
```
```

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

### Average a column per interval

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Computes the average of a column's values across records in each time period. This is useful for metrics like average weight or price over time.

```php
use Flowframe\Trend\Trend;
use App\Models\User;

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

```

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

### Use a custom date column

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Overrides the default `created_at` column used for date filtering and grouping. Use this when your model tracks time via a different column.

```APIDOC
## `->dateColumn()` — Use a custom date column

Overrides the default `created_at` column used for date filtering and grouping. Use this when your model tracks time via a different column.

```php
use Flowframe\Trend\Trend;
use App\Models\Order;

$trend = Trend::model(Order::class)
    ->dateColumn('shipped_at')        // group by shipped_at instead of created_at
    ->between(
        start: now()->startOfMonth(),
        end: now()->endOfMonth(),
    )
    ->perDay()
    ->count();
```
```

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

### Sum a column per interval

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Sums the values of a given column across all records in each time period. The result can be mapped to display values in a more readable format.

```php
use Flowframe\Trend\Trend;
use App\Models\Order;

$revenue = Trend::model(Order::class)
    ->between(now()->startOfYear(), now()->endOfYear())
    ->perMonth()
    ->sum('total_price_in_cents');

$revenueByMonth = $revenue->mapWithKeys(
    fn ($v) => [$v->date => $v->aggregate / 100]
);

```

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

### Minimum value of a column per interval

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Returns the minimum value of a specified column for each time period. The result is a collection of TrendValue objects, each containing a date and the minimum value.

```APIDOC
## `->min()` — Minimum value of a column per interval

Returns the minimum value of a column in each time period.

```php
use Flowframe\Trend\Trend;
use App\Models\SensorReading;

$minTemp = Trend::model(SensorReading::class)
    ->between(now()->startOfWeek(), now()->endOfWeek())
    ->perDay()
    ->min('temperature');
```
```

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

### Maximum value of a column per interval

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Returns the maximum value of a specified column for each time period. The result is a collection of TrendValue objects, each containing a date and the maximum value.

```APIDOC
## `->max()` — Maximum value of a column per interval

Returns the maximum value of a column in each time period.

```php
use Flowframe\Trend\Trend;
use App\Models\SensorReading;

$maxTemp = Trend::model(SensorReading::class)
    ->between(now()->startOfWeek(), now()->endOfWeek())
    ->perDay()
    ->max('temperature');
```
```

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

### Set a custom SQL alias for the date column

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Overrides the default `date` SQL alias used in the `GROUP BY` and `SELECT` clauses. Useful if `date` conflicts with a reserved word on your database.

```APIDOC
## `->dateAlias()` — Set a custom SQL alias for the date column

Overrides the default `date` SQL alias used in the `GROUP BY` and `SELECT` clauses. Useful if `date` conflicts with a reserved word on your database.

```php
use Flowframe\Trend\Trend;
use App\Models\Order;

$trend = Trend::model(Order::class)
    ->dateAlias('trend_date')
    ->between(now()->startOfYear(), now()->endOfYear())
    ->perMonth()
    ->count();
```
```

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

### Sum a column per interval

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Sums the values of a given column across all records in each time period. The result is a collection of TrendValue objects, each containing a date and the aggregated sum.

```APIDOC
## `->sum()` — Sum a column per interval

Sums the values of a given column across all records in each time period.

```php
use Flowframe\Trend\Trend;
use App\Models\Order;

$revenue = Trend::model(Order::class)
    ->between(now()->startOfYear(), now()->endOfYear())
    ->perMonth()
    ->sum('total_price_in_cents');

// [ 
//   TrendValue { date: "2024-01", aggregate: 4823700 },
//   TrendValue { date: "2024-02", aggregate: 0        },
//   TrendValue { date: "2024-03", aggregate: 6102500 },
//   ...
// ]

$revenueByMonth = $revenue->mapWithKeys(
    fn ($v) => [$v->date => $v->aggregate / 100]
);
// ["2024-01" => 48237.00, "2024-02" => 0.0, "2024-03" => 61025.00, ...]
```
```

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

### Set a custom SQL alias for the date column

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Overrides the default `date` SQL alias used in the `GROUP BY` and `SELECT` clauses. This is useful if `date` conflicts with a reserved word on your database.

```php
use Flowframe\Trend\Trend;
use App\Models\Order;

$trend = Trend::model(Order::class)
    ->dateAlias('trend_date')
    ->between(now()->startOfYear(), now()->endOfYear())
    ->perMonth()
    ->count();

```

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

### TrendValue object usage

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Iterate through the `TrendValue` collection to access formatted dates and aggregated values. The results can be easily converted to JSON for charting libraries.

```php
use Flowframe\Trend\Trend;
use Flowframe\Trend\TrendValue;
use App\Models\Order;

$trend = Trend::model(Order::class)
    ->between(now()->startOfYear(), now()->endOfYear())
    ->perMonth()
    ->count();

$trend->each(function (TrendValue $value) {
    echo "Date: {$value->date}, Count: {$value->aggregate}\n";
});

// Convert to array for JSON response:
return response()->json([
    'labels' => $trend->pluck('date'),
    'data'   => $trend->pluck('aggregate'),
]);

```

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

### TrendValue Object

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Represents a single data point in the trend results. Each TrendValue instance has a `date` property (formatted string) and an `aggregate` property (the computed numeric value or 0 for gaps).

```APIDOC
## `TrendValue` — The result value object

Every item in the returned `Collection` is a `TrendValue` instance with two public properties: `date` (a formatted string matching the selected interval) and `aggregate` (the computed numeric value, or `0` for gap-filled periods).

```php
use Flowframe\Trend\Trend;
use Flowframe\Trend\TrendValue;
use App\Models\Order;

$trend = Trend::model(Order::class)
    ->between(now()->startOfYear(), now()->endOfYear())
    ->perMonth()
    ->count();

$trend->each(function (TrendValue $value) {
    echo "Date: {$value->date}, Count: {$value->aggregate}\n";
});

// Convert to array for JSON response:
return response()->json([
    'labels' => $trend->pluck('date'),
    'data'   => $trend->pluck('aggregate'),
]);

// Output:
// {
//   "labels": ["2024-01","2024-02","2024-03",...,"2024-12"],
//   "data":   [142, 0, 198, ..., 310]
// }
```
```

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

### Average a column per interval

Source: https://context7.com/flowframe/laravel-trend/llms.txt

Computes the average of a column's values across records in each time period. The result is a collection of TrendValue objects, each containing a date and the computed average.

```APIDOC
## `->average()` — Average a column per interval

Computes the average of a column's values across records in each time period.

```php
use Flowframe\Trend\Trend;
use App\Models\User;

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

// [ 
//   TrendValue { date: "2014", aggregate: "72.40" },
//   TrendValue { date: "2015", aggregate: "74.10" },
//   ...
// ]
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.