DirectoryTree Metrics

https://github.com/directorytree/metrics
Admin
DirectoryTree Metrics provides a simple and elegant way to record and query various countable events...
Tokens:9,820
Snippets:98
Trust Score:7.3
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Package and Run Migrations

Source: https://context7.com/directorytree/metrics/llms.txt

Install the package using Composer, publish and run migrations, and optionally publish the configuration file.

```bash
composer require directorytree/metrics

php artisan vendor:publish --tag="metrics-migrations"

php artisan migrate

php artisan vendor:publish --tag="metrics-config"
```

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

### Install DirectoryTree Metrics Package

Source: https://github.com/directorytree/metrics/blob/master/README.md

Install the package using Composer. After installation, publish and run the migrations to set up the necessary database tables.

```bash
composer require directorytree/metrics
```

```bash
php artisan vendor:publish --tag="metrics-migrations"
```

```bash
php artisan migrate
```

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

### Enable Automatic Metric Capturing in AppServiceProvider

Source: https://github.com/directorytree/metrics/blob/master/README.md

Configure your `AppServiceProvider` to automatically start capturing metrics on application boot, ensuring all recorded metrics are batched and committed.

```php
// app/Providers/AppServiceProvider.php

use DirectoryTree\Metrics\Facades\Metrics;

class AppServiceProvider extends ServiceProvider
{
    // ...

    public function boot(): void
    {
        Metrics::capture();
    }
}
```

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

### Record Basic Metrics with metric() Helper

Source: https://context7.com/directorytree/metrics/llms.txt

Use the global metric() helper for simple metric recording. The value defaults to 1 if not specified. Multiple recordings of the same metric are summed.

```php
use Carbon\Carbon;

// Basic metric recording (value defaults to 1)
metric('signups')->record();

// Record with a custom value
metric('api:requests')->record(10);

// Multiple recordings of same metric are summed (database will contain value: 2)
metric('auth:logins')->record();
metric('auth:logins')->record();
```

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

### Publish Configuration File

Source: https://github.com/directorytree/metrics/blob/master/README.md

Optionally, publish the configuration file to customize driver and queueing behavior. This creates a `config/metrics.php` file.

```bash
php artisan vendor:publish --tag="metrics-config"
```

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

### Record a Simple Metric using Helper

Source: https://github.com/directorytree/metrics/blob/master/README.md

Record a metric using the global `metric` helper function. This provides a more concise syntax for logging events.

```php
metric('signups')->record();
```

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

### Configuration Options for Metrics

Source: https://context7.com/directorytree/metrics/llms.txt

Configure the metrics driver, queueing behavior, and Redis settings via the config file or environment variables. The 'array' driver is in-memory, while 'redis' is distributed.

```php
// config/metrics.php
return [
    // Driver: 'array' (in-memory) or 'redis' (distributed)
    'driver' => env('METRICS_DRIVER', 'array'),

    // Queue metric recording for high-traffic apps
    'queue' => env('METRICS_QUEUE', false) ? [
        'name' => env('METRICS_QUEUE_NAME'),
        'connection' => env('METRICS_QUEUE_CONNECTION', env('QUEUE_CONNECTION', 'sync')),
    ] : false,

    // Auto-commit metrics on application termination
    'auto_commit' => env('METRICS_AUTO_COMMIT', true),

    // Redis configuration for 'redis' driver
    'redis' => [
        'connection' => env('METRICS_REDIS_CONNECTION'),
        'key' => env('METRICS_REDIS_KEY', 'metrics:pending'),
        'ttl' => env('METRICS_REDIS_TTL', 86400), // 1 day
    ],
];
```

```dotenv
// Environment variables
// .env
METRICS_DRIVER=redis
METRICS_QUEUE=true
METRICS_QUEUE_NAME=metrics
METRICS_AUTO_COMMIT=false
METRICS_REDIS_CONNECTION=default
METRICS_REDIS_KEY=metrics:pending
METRICS_REDIS_TTL=86400
```

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

### Record Metrics with Metrics Facade

Source: https://context7.com/directorytree/metrics/llms.txt

Utilize the Metrics facade for direct access to the MetricManager, recording metrics using the MetricData class.

```php
use DirectoryTree\Metrics\MetricData;
use DirectoryTree\Metrics\Facades\Metrics;

// Record using MetricData class
Metrics::record(new MetricData('signups'));

// Record with all options via MetricData constructor
Metrics::record(new MetricData(
    name: 'page:views',
    category: 'blog',
    value: 5,
    date: now(),
    measurable: null,
    additional: [
        'source' => 'google',
        'country' => 'US',
    ]
));
```

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

### Record a Simple Metric using Facade

Source: https://github.com/directorytree/metrics/blob/master/README.md

Record a metric using the `Metrics` facade by passing a `MetricData` object. This is one of the ways to log a countable event.

```php
use DirectoryTree\Metrics\MetricData;
use DirectoryTree\Metrics\Facades\Metrics;

Metrics::record(new MetricData('signups'));
```

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

### Record Hourly Metrics

Source: https://github.com/directorytree/metrics/blob/master/README.md

Enable hour-level granularity for metrics using the `hourly()` method. This is useful for tracking metrics that require fine-grained temporal analysis.

```php
// Track API requests by hour
metric('api:requests')
    ->hourly()
    ->record();
```

```php
use Carbon\Carbon;

// Record API requests for a specific hour
metric('api:requests')
    ->date(Carbon::parse('2025-10-19 14:30:00'))
    ->hourly()
    ->record();

// This will be stored with hour = 14
```

```php
metric('page:views')->record();         // Daily metric (hour = null)
metric('page:views')->hourly()->record(); // Hourly metric (hour = current hour)
```

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

### Record Hourly Metrics

Source: https://context7.com/directorytree/metrics/llms.txt

Enable hour-level granularity for precise time tracking using the hourly() method. Metrics are stored separately for daily and hourly granularity.

```php
use Carbon\Carbon;

// Track API requests by hour (stores hour 0-23)
metric('api:requests')
    ->hourly()
    ->record();

// Record for a specific hour
metric('api:requests')
    ->date(Carbon::parse('2025-10-19 14:30:00'))
    ->hourly()
    ->record(); // Stored with hour = 14

// Hourly and daily metrics are stored separately
metric('page:views')->record();           // Daily metric (hour = null)
metric('page:views')->hourly()->record(); // Hourly metric (hour = current hour)
```

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

### Record Metrics with Categories using metric() Helper

Source: https://context7.com/directorytree/metrics/llms.txt

Segment metrics by assigning categories using the category() method before recording. This allows for more granular analysis.

```php
// Record with a category to segment metrics
metric('api:requests')->category('users')->record();
metric('api:requests')->category('orders')->record();
metric('purchases')->category('stripe')->record();
```

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

### Implement Custom Metric Repository

Source: https://context7.com/directorytree/metrics/llms.txt

Implement the `MetricRepository` interface to create custom storage for metrics before they are committed. Bind this custom repository in your `AppServiceProvider`.

```php
namespace App\Metrics;

use DirectoryTree\Metrics\Measurable;
use DirectoryTree\Metrics\MetricRepository;

class CustomMetricRepository implements MetricRepository
{
    protected array $metrics = [];

    public function add(Measurable $metric): void
    {
        $this->metrics[] = $metric;
    }

    public function all(): array
    {
        return $this->metrics;
    }

    public function flush(): void
    {
        $this->metrics = [];
    }
}
```

```php
// Bind in AppServiceProvider
use App\Metrics\CustomMetricRepository;
use DirectoryTree\Metrics\MetricRepository;

public function register(): void
{
    $this->app->singleton(MetricRepository::class, CustomMetricRepository::class);
}
```

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

### Record a Simple Metric using PendingMetric

Source: https://github.com/directorytree/metrics/blob/master/README.md

Record a metric using the `PendingMetric` class directly. This offers another way to log events, especially when creating metrics outside of the typical request cycle.

```php
use DirectoryTree\Metrics\PendingMetric;

PendingMetric::make('signups')->record();
```

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

### Record Metrics with Categories

Source: https://github.com/directorytree/metrics/blob/master/README.md

Organize metrics into distinct categories for better tracking and analysis. Each category creates a separate metric entry.

```php
// Track API calls by endpoint
metric('api:requests')->category('users')->record();
metric('api:requests')->category('orders')->record();

// Track errors by severity
metric('app:errors')->category('critical')->record();
metric('app:errors')->category('warning')->record();

// Track purchases by payment method
metric('purchases')->category('stripe')->record();
metric('purchases')->category('paypal')->record();
```

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

### Add Custom Columns to Metrics Table

Source: https://github.com/directorytree/metrics/blob/master/README.md

Create a database migration to add custom columns like 'source', 'country', and 'device' to the 'metrics' table for storing additional context.

```php
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('metrics', function (Blueprint $table) {
    $table->string('source')->nullable()->index();
    $table->string('country')->nullable()->index();
    $table->string('device')->nullable();
});
```

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

### Testing Metrics with MetricFake

Source: https://context7.com/directorytree/metrics/llms.txt

Use the fake implementation to assert metrics were recorded correctly in your tests without touching the database. Assert by name, with closures for complex conditions, or assert that metrics were not recorded.

```php
use DirectoryTree\Metrics\Measurable;
use DirectoryTree\Metrics\Facades\Metrics;

public function test_user_signup_records_metric()
{
    Metrics::fake();

    // Your code that records metrics...
    $this->post('register', [
        'email' => 'user@example.com',
        'password' => 'password',
    ]);

    // Assert metric was recorded by name
    Metrics::assertRecorded('signups');
}
```

```php
public function test_api_call_records_metric_with_category()
{
    Metrics::fake();

    $this->getJson('api/users');

    // Assert with closure for complex conditions
    Metrics::assertRecorded(fn (Measurable $metric) =>
        $metric->name() === 'api:requests' &&
        $metric->category() === 'users'
    );
}
```

```php
public function test_failed_login_does_not_record_success_metric()
{
    Metrics::fake();

    $this->post('login', ['email' => 'wrong@example.com', 'password' => 'wrong']);

    // Assert metric was NOT recorded
    Metrics::assertNotRecorded('auth:logins');
    Metrics::assertRecorded('auth:attempts');
}
```

```php
public function test_batch_job_records_correct_count()
{
    Metrics::fake();

    Artisan::call('orders:process');

    // Assert specific number of recordings
    Metrics::assertRecordedTimes('orders:processed', 100);
}
```

```php
public function test_no_metrics_recorded_on_error()
{
    Metrics::fake();

    // Code that should not record metrics...

    Metrics::assertNothingRecorded();
}
```

```php
public function test_access_recorded_metrics()
{
    Metrics::fake();

    metric('api:requests')->category('users')->record();
    metric('api:requests')->category('orders')->record();

    // Get all recorded metrics
    $all = Metrics::recorded();

    // Get by name
    $apiCalls = Metrics::recorded('api:requests'); // Collection of 2

    // Get with closure filter
    $userEndpoint = Metrics::recorded(fn ($metric) =>
        $metric->category() === 'users'
    ); // Collection of 1
}
```

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

### Configure Redis Driver for Metrics

Source: https://github.com/directorytree/metrics/blob/master/README.md

Set the metrics driver to 'redis' in the configuration file or via an environment variable for distributed applications or high-traffic scenarios.

```php
// config/metrics.php

return [
    'driver' => 'redis',
    
    // ...
];
```

```env
METRICS_DRIVER=redis
```

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

### Implement Custom Metric Manager

Source: https://context7.com/directorytree/metrics/llms.txt

Implement the `MetricManager` interface to define custom logic for recording, committing, capturing, and managing metrics. Bind this custom manager in your `AppServiceProvider`.

```php
namespace App\Metrics;

use DirectoryTree\Metrics\Measurable;
use DirectoryTree\Metrics\MetricManager;

class CustomMetricManager implements MetricManager
{
    public function record(Measurable $metric): void
    {
        // Custom recording logic (e.g., send to external service)
    }

    public function commit(): int
    {
        // Custom commit logic
        return 0;
    }

    public function capture(): void
    {
        // Start capturing
    }

    public function isCapturing(): bool
    {
        return false;
    }

    public function stopCapturing(): void
    {
        // Stop capturing
    }
}
```

```php
// Bind in AppServiceProvider
use App\Metrics\CustomMetricManager;
use DirectoryTree\Metrics\MetricManager;

public function register(): void
{
    $this->app->singleton(MetricManager::class, CustomMetricManager::class);
}
```

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

### Bind Custom Metric Repository in Service Provider

Source: https://github.com/directorytree/metrics/blob/master/README.md

Register your custom metric repository implementation in the `AppServiceProvider` by binding it to the `MetricRepository` interface using `singleton`.

```php
use App\Metrics\CustomMetricRepository;
use DirectoryTree\Metrics\MetricRepository;

public function register(): void
{
    $this->app->singleton(MetricRepository::class, CustomMetricRepository::class);
}
```

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

### Record Metrics with Custom Attributes

Source: https://context7.com/directorytree/metrics/llms.txt

Add custom columns to the metrics table via migration and use the `with()` method to store additional context with metrics. Custom attributes affect metric uniqueness.

```php
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
use DirectoryTree\Metrics\Metric;

// First, add custom columns via migration
Schema::table('metrics', function (Blueprint $table) {
    $table->string('source')->nullable()->index();
    $table->string('country')->nullable()->index();
    $table->string('device')->nullable();
});

// Record with custom attributes
metric('views')
    ->measurable(Post::find(1))
    ->with(['source' => 'google'])
    ->record();

metric('conversions')
    ->with([
        'source' => 'facebook',
        'country' => 'US',
        'device' => 'mobile',
    ])
    ->record();

// Custom attributes are part of uniqueness (creates separate metrics)
metric('page:views')->with(['source' => 'google'])->record();   // Creates metric #1
metric('page:views')->with(['source' => 'facebook'])->record(); // Creates metric #2
metric('page:views')->with(['source' => 'google'])->record();   // Increments metric #1

// Query by custom attributes
$googleViews = Metric::where('name', 'page:views')
    ->where('source', 'google')
    ->sum('value');

$mobileViews = Metric::today()
    ->where('name', 'page:views')
    ->where('device', 'mobile')
    ->sum('value');
```

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

### Record Metrics with Specific Dates using metric() Helper

Source: https://context7.com/directorytree/metrics/llms.txt

Record metrics for specific past or future dates using the date() method with a Carbon instance. Defaults to the current date.

```php
// Record with a specific date (default is today)
metric('signups')
    ->date(Carbon::parse('2025-01-15'))
    ->record(50);

metric('jobs:completed')
    ->date(Carbon::yesterday())
    ->record(1250);
```

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

### Capture and Commit Metrics in Batches

Source: https://github.com/directorytree/metrics/blob/master/README.md

For high-performance scenarios, capture metrics in memory and commit them in batches to reduce database load. Captured metrics are automatically committed on application termination.

```php
use DirectoryTree\Metrics\Facades\Metrics;

Metrics::capture();

// Record multiple metrics...
metric('signups')->record();
metric('notifications:sent')->category('welcome')->record();
metric('signups')->record();

// Commit all captured metrics at once
Metrics::commit();
```

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

### Manually Commit Metrics from Redis

Source: https://github.com/directorytree/metrics/blob/master/README.md

Run the `metrics:commit` Artisan command manually to commit metrics stored in Redis to the database. This is an alternative to scheduling the command.

```bash
php artisan metrics:commit
```

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

### Record Metrics with Custom Attributes

Source: https://github.com/directorytree/metrics/blob/master/README.md

Use the `with()` method to attach custom attributes to metrics, enabling segmentation by dimensions like traffic source, country, or device.

```php
// Track post views with traffic source
metric('views')
    ->measurable(Post::find(1))
    ->with(['source' => 'google'])
    ->record();
```

```php
// Track conversions with multiple attributes
metric('conversions')
    ->with([
        'source' => 'facebook',
        'country' => 'US',
        'device' => 'mobile',
    ])
    ->record();
```

```php
// Track API requests for a user within a team
metric('api:requests')
    ->measurable(Auth::user())
    ->with(['team_id' => 123])
    ->record();
```

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

### Query Metrics by Date Range

Source: https://github.com/directorytree/metrics/blob/master/README.md

Use these methods to retrieve metrics within specific date ranges. Ensure Carbon is imported for date parsing.

```php
use DirectoryTree\Metrics\Metric;

// Get today's metrics
$metrics = Metric::today()->get();

// Get this week's metrics
$metrics = Metric::thisWeek()->get();

// Get this month's metrics
$metrics = Metric::thisMonth()->get();

// Get this year's metrics
$metrics = Metric::thisYear()->get();

// Get yesterday's metrics
$metrics = Metric::yesterday()->get();

// Get last week's metrics
$metrics = Metric::lastWeek()->get();

// Get last month's metrics
$metrics = Metric::lastMonth()->get();

// Get last year's metrics
$metrics = Metric::lastYear()->get();

// Get metrics between specific dates
$metrics = Metric::betweenDates(
    Carbon::parse('2025-01-01'),
    Carbon::parse('2025-12-31')
)->get();

// Get metrics on a specific date
$metrics = Metric::onDate(Carbon::parse('2025-10-15'))->get();
```

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

### Capture and Batch Commit Metrics

Source: https://context7.com/directorytree/metrics/llms.txt

Capture metrics in memory and commit them in batches for improved performance in high-traffic scenarios. Capturing can be enabled globally in AppServiceProvider.

```php
use DirectoryTree\Metrics\Facades\Metrics;

// Start capturing metrics
Metrics::capture();

// Record multiple metrics (held in memory)
metric('signups')->record();
metric('notifications:sent')->category('welcome')->record();
metric('signups')->record();

// Commit all captured metrics at once
Metrics::commit();

// Stop capturing without committing
Metrics::stopCapturing();

// Check if currently capturing
if (Metrics::isCapturing()) {
    // ...
}

// Enable capturing for entire application in AppServiceProvider
// app/Providers/AppServiceProvider.php
use DirectoryTree\Metrics\Facades\Metrics;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Metrics::capture(); // Auto-commits on application termination
    }
}
```

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

### Record Metrics with PendingMetric Class

Source: https://context7.com/directorytree/metrics/llms.txt

Use the PendingMetric class for an object-oriented approach to building and recording metrics, offering full access to all configuration options.

```php
use DirectoryTree\Metrics\PendingMetric;
use Carbon\Carbon;

// Create and record a metric
PendingMetric::make('signups')->record();

// Full example with all options
PendingMetric::make('page:views')
    ->category('blog')
    ->date(Carbon::parse('2025-10-15'))
    ->with(['source' => 'google', 'country' => 'US'])
    ->record(5);

// Using a custom model for storage
PendingMetric::make('api:requests')
    ->model(App\Models\ApiMetric::class)
    ->category('external')
    ->record();
```

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

### Record Metrics with MetricData Class

Source: https://github.com/directorytree/metrics/blob/master/README.md

Use the `MetricData` class to record metrics with custom attributes programmatically, especially useful when not using the fluent `metric()` helper.

```php
use DirectoryTree\Metrics\MetricData;
use DirectoryTree\Metrics\Facades\Metrics;

Metrics::record(new MetricData(
    name: 'page:views',
    additional: [
        'source' => 'google',
        'country' => 'US',
    ]
));
```

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

### Bind Custom Metric Manager in Service Provider

Source: https://github.com/directorytree/metrics/blob/master/README.md

Register your custom metric manager implementation in the `AppServiceProvider` by binding it to the `MetricManager` interface using `singleton`.

```php
use App\Metrics\CustomMetricManager;
use DirectoryTree\Metrics\MetricManager;

public function register(): void
{
    $this->app->singleton(MetricManager::class, CustomMetricManager::class);
}
```

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

### Test Metric Recording with Fake Implementation

Source: https://github.com/directorytree/metrics/blob/master/README.md

Use `Metrics::fake()` to mock the metrics system in tests. This allows you to assert that specific metrics were recorded or not recorded without actually persisting them.

```php
use DirectoryTree\Metrics\Measurable;
use DirectoryTree\Metrics\Facades\Metrics;

public function test_user_signup_records_metric()
{
    Metrics::fake();

    // Your code that records metrics...
    $this->post('register', [
        'email' => 'user@example.com',
        'password' => 'password',
    ]);

    // Assert metrics were recorded
    Metrics::assertRecorded('signups');
}

public function test_api_call_records_metric_with_endpoint()
{
    Metrics::fake();

    $this->getJson('api/users');

    // Assert metrics were recorded with a closure
    Metrics::assertRecorded(fn (Measurable $metric) =>
        $metric->name() === 'api:requests' &&
        $metric->category() === 'users'
    );
}

public function test_failed_login_records_metric()
{
    Metrics::fake();

    $this->post('login', [
        'email' => 'wrong@example.com',
        'password' => 'wrong',
    ]);

    // Assert metrics were not recorded
    Metrics::assertNotRecorded('auth:logins');

    // Assert failed login was recorded
    Metrics::assertRecorded('auth:attempts');
}

public function test_purchase_records_metric_for_user()
{
    Metrics::fake();

    $user = User::factory()->create();

    $this->actingAs($user)->post('purchases', [
        'product_id' => 1,
    ]);

    // Assert metrics were recorded with model
    Metrics::assertRecorded(fn ($metric) =>
        $metric->name() === 'purchases' &&
        $metric->measurable()?->is($user)
    );
}

public function test_batch_job_records_metrics()
{
    Metrics::fake();

    // Run your batch job
    Artisan::call('orders:process');

    // Assert metrics were recorded a specific number of times
    Metrics::assertRecordedTimes('orders:processed', 100);
}
```

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

### Define a Custom Metric Model

Source: https://github.com/directorytree/metrics/blob/master/README.md

Create a custom Eloquent model for metrics by extending `Model` and ensuring it has the required unguarded properties and casts matching the default `Metric` model. This allows for global customization of metric storage.

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class CustomMetric extends Model
{
    protected $guarded = [];

    protected function casts(): array
    {
        return [
            'year' => 'integer',
            'month' => 'integer',
            'day' => 'integer',
            'hour' => 'integer',
            'value' => 'integer',
        ];
    }
}
```

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

### Query Hourly Metrics

Source: https://github.com/directorytree/metrics/blob/master/README.md

Query hourly metrics using specific methods like `thisHour()`, `lastHour()`, and `onDateTime()`. These methods allow filtering metrics by precise time ranges.

```php
use DirectoryTree\Metrics\Metric;

// Get metrics for this hour
$metrics = Metric::thisHour()->get();

// Get metrics for last hour
$metrics = Metric::lastHour()->get();

// Get metrics for a specific date and hour
$metrics = Metric::onDateTime(Carbon::parse('2025-10-19 14:00:00'))->get();

// Get API requests for the current hour
$requests = Metric::thisHour()
    ->where('name', 'api:requests')
    ->sum('value');
```

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

### Access Recorded Metrics in Tests

Source: https://github.com/directorytree/metrics/blob/master/README.md

After faking the metrics system, you can retrieve and inspect the recorded metrics using `Metrics::recorded()`. This is useful for verifying complex metric data or filtering by specific criteria.

```php
Metrics::fake();

metric('api:requests')->category('users')->record();

// Get all recorded metrics
$all = Metrics::recorded();

// Get metrics by name
$apiCalls = Metrics::recorded('api:requests');

// Get metrics with a closure
$userEndpoint = Metrics::recorded(fn ($metric) =>
    $metric->category() === 'users'
);
```

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

### Record Metrics with Custom Dates

Source: https://github.com/directorytree/metrics/blob/master/README.md

Specify a custom date for recording metrics, useful for backfilling data or recording historical events. Requires the Carbon library for date manipulation.

```php
use Carbon\Carbon;

// Backfill signup data from an import
metric('signups')
    ->date(Carbon::parse('2025-01-15'))
    ->record(50);

// Record yesterday's batch job completions
metric('jobs:completed')
    ->date(Carbon::yesterday())
    ->record(1250);
```

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

### Query Metrics with Date Filters

Source: https://context7.com/directorytree/metrics/llms.txt

Utilize the `Metric` model's query builder for convenient date filtering, including predefined time ranges and custom date ranges. Supports chaining with Eloquent methods for complex analysis.

```php
use DirectoryTree\Metrics\Metric;
use Carbon\Carbon;

// Time-based queries
$todayMetrics = Metric::today()->get();
$yesterdayMetrics = Metric::yesterday()->get();
$thisWeekMetrics = Metric::thisWeek()->get();
$lastWeekMetrics = Metric::lastWeek()->get();
$thisMonthMetrics = Metric::thisMonth()->get();
$lastMonthMetrics = Metric::lastMonth()->get();
$thisQuarterMetrics = Metric::thisQuarter()->get();
$lastQuarterMetrics = Metric::lastQuarter()->get();
$thisYearMetrics = Metric::thisYear()->get();
$lastYearMetrics = Metric::lastYear()->get();

// Date range queries
$metrics = Metric::betweenDates(
    Carbon::parse('2025-01-01'),
    Carbon::parse('2025-12-31')
)->get();

// Specific date
$metrics = Metric::onDate(Carbon::parse('2025-10-15'))->get();

// Hourly queries
$thisHourMetrics = Metric::thisHour()->get();
$lastHourMetrics = Metric::lastHour()->get();
$specificHour = Metric::onDateTime(Carbon::parse('2025-10-19 14:00:00'))->get();

// Chain with Eloquent methods
$signups = Metric::today()
    ->where('name', 'signups')
    ->sum('value');

$apiUsageByEndpoint = Metric::thisMonth()
    ->where('name', 'api:requests')
    ->get()
    ->groupBy('category')
    ->map->sum('value');

$hourlyApiRequests = Metric::thisHour()
    ->where('name', 'api:requests')
    ->sum('value');
```

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

### Schedule Metrics Commit Command

Source: https://github.com/directorytree/metrics/blob/master/README.md

Schedule the `metrics:commit` Artisan command to periodically commit metrics from Redis to the database. Ensure `auto_commit` is disabled in the configuration if using this method.

```php
// app/Console/Kernel.php

protected function schedule(Schedule $schedule): void
{
    $schedule->command('metrics:commit')->hourly();
}
```

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

### Query Metrics by Custom Attributes

Source: https://github.com/directorytree/metrics/blob/master/README.md

Retrieve and analyze metrics by filtering on custom attributes using standard Eloquent query methods.

```php
// Get page views by source
$googleViews = Metric::where('name', 'page:views')
    ->where('source', 'google')
    ->sum('value');
```

```php
// Get conversions by country this month
$conversions = Metric::thisMonth()
    ->where('name', 'conversions')
    ->get()
    ->groupBy('country')
    ->map->sum('value');
```

```php
// Get mobile vs desktop traffic
$mobileViews = Metric::today()
    ->where('name', 'page:views')
    ->where('device', 'mobile')
    ->sum('value');
```

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

### Using Redis Driver with Scheduled Commits

Source: https://context7.com/directorytree/metrics/llms.txt

Configure the Redis driver for distributed applications and schedule periodic commits to reduce database load. Disable auto-commit when using scheduled commits.

```bash
# Set environment variable
METRICS_DRIVER=redis
```

```php
// config/metrics.php
return [
    'driver' => 'redis',
    'auto_commit' => false, // Disable auto-commit when using scheduled commits
    // ...
];

// app/Console/Kernel.php
use Illuminate\Console\Scheduling\Schedule;

protected function schedule(Schedule $schedule): void
{
    // Commit metrics from Redis to database hourly
    $schedule->command('metrics:commit')->hourly();
}

// Or run manually
// php artisan metrics:commit
```

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

### Register Custom Metric Model Globally

Source: https://github.com/directorytree/metrics/blob/master/README.md

In your `AppServiceProvider`, use `DatabaseMetricManager::useModel()` to set your custom metric model as the default for all metric operations. This ensures all metrics adhere to your custom model's structure and behavior.

```php
use App\Models\CustomMetric;
use DirectoryTree\Metrics\DatabaseMetricManager;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    DatabaseMetricManager::useModel(CustomMetric::class);
}
```

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

### Custom Metric Model

Source: https://context7.com/directorytree/metrics/llms.txt

Use a custom Eloquent model globally or per-metric for advanced customization and separate storage tables. Ensure the model has a guarded property and casts for relevant columns.

```php
// Create custom metric model
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class CustomMetric extends Model
{
    protected $guarded = [];

    protected function casts(): array
    {
        return [
            'year' => 'integer',
            'month' => 'integer',
            'day' => 'integer',
            'hour' => 'integer',
            'value' => 'integer',
        ];
    }
}

// Set as global default in AppServiceProvider
use App\Models\CustomMetric;
use DirectoryTree\Metrics\DatabaseMetricManager;

public function boot(): void
{
    DatabaseMetricManager::useModel(CustomMetric::class);
}

// Or use per-metric with separate tables
use App\Models\ApiMetric;
use App\Models\UserMetric;

metric('requests')
    ->model(ApiMetric::class)
    ->record();

metric('user:logins')
    ->model(UserMetric::class)
    ->with(['user_id' => Auth::id()])
    ->record();
```

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

### Chain Metrics Queries with Eloquent

Source: https://github.com/directorytree/metrics/blob/master/README.md

Combine date filtering with standard Eloquent methods like `where` and `sum` to aggregate specific metric data. Useful for calculating totals or grouping by categories.

```php
// Get today's signups
$signups = Metric::today()
    ->where('name', 'signups')
    ->sum('value');

// Get this week's purchases
$purchases = Metric::thisWeek()
    ->where('name', 'purchases')
    ->sum('value');

// Get API usage by endpoint this month
$apiUsage = Metric::thisMonth()
    ->where('name', 'api:requests')
    ->get()
    ->groupBy('category')
    ->map->sum('value');

// Count unique metrics recorded today
$count = Metric::today()->count();
```

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

### Assign Custom Model to a Metric

Source: https://github.com/directorytree/metrics/blob/master/README.md

Use the `model()` method on a `PendingMetric` to specify a custom Eloquent model for storing metric data. This requires duplicating the metrics table structure for each custom model.

```php
use App\Models\ApiMetric;
use App\Models\UserMetric;

// Store API metrics in a separate table
metric('requests')
    ->model(ApiMetric::class)
    ->record();

// Store user metrics in another table
metric('user:logins')
    ->model(UserMetric::class)
    ->with(['user_id' => Auth::id()])
    ->record();

// Use the default model
metric('page:views')->record();
```

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

### Query Metrics for Eloquent Models

Source: https://context7.com/directorytree/metrics/llms.txt

Query metrics associated with a specific Eloquent model using the metrics() relationship and chain query builder methods.

```php
// Query metrics for a specific model
$user = User::find(1);

$totalLogins = $user->metrics()
    ->where('name', 'auth:logins')
    ->sum('value');

$ordersThisMonth = $customer->metrics()
    ->where('name', 'orders')
    ->thisMonth()
    ->sum('value');
```

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

### Uniqueness Check with Custom Attributes

Source: https://github.com/directorytree/metrics/blob/master/README.md

Metrics with different custom attribute values are stored separately, allowing for distinct tracking and aggregation.

```php
metric('page:views')->with(['source' => 'google'])->record();   // Creates metric #1
metric('page:views')->with(['source' => 'facebook'])->record(); // Creates metric #2
metric('page:views')->with(['source' => 'google'])->record();   // Increments metric #1
```

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

### Associate Metrics with Eloquent Models

Source: https://context7.com/directorytree/metrics/llms.txt

Use the HasMetrics trait in your Eloquent models to associate metrics polymorphically using the measurable() method.

```php
use DirectoryTree\Metrics\HasMetrics;
use Illuminate\Database\Eloquent\Model;

// Add trait to your model
class User extends Model
{
    use HasMetrics;
}

class Customer extends Model
{
    use HasMetrics;
}

// Record metrics associated with models
metric('auth:logins')
    ->measurable(Auth::user())
    ->record();

metric('orders')
    ->measurable(Customer::find(123))
    ->record();

metric('api:requests')
    ->measurable($apiClient)
    ->category('external')
    ->record(50);
```

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

### Record Metric with Custom Value

Source: https://github.com/directorytree/metrics/blob/master/README.md

Specify a custom value when recording a metric, useful for tracking quantities like multiple API calls or batch job completions. If the same metric is recorded multiple times, values are summed.

```php
// Track multiple API calls at once
metric('api:requests')->record(10);

// Track batch job completions
metric('jobs:completed')->record(250);
```

```php
metric('auth:logins')->record(); // value: 1
metric('auth:logins')->record(); // value: 1

// Database will contain one metric with value: 2
```

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

### Stop Capturing Metrics Manually

Source: https://github.com/directorytree/metrics/blob/master/README.md

Manually stop the in-memory capturing of metrics when batch processing is no longer needed.

```php
Metrics::stopCapturing();
```

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

### Associate Metrics with Eloquent Models

Source: https://github.com/directorytree/metrics/blob/master/README.md

Use the `HasMetrics` trait to associate metrics with Eloquent models. This allows for recording and querying metrics specific to individual model instances.

```php
use DirectoryTree\Metrics\HasMetrics;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use HasMetrics;
}
```

```php
// Track logins per user
metric('auth:logins')
    ->measurable(Auth::user())
    ->record();

// Track orders per customer
metric('orders')
    ->measurable(Customer::find(...))
    ->record();

// Track API calls per client
metric('api:requests')
    ->measurable(ApiClient::find(...))
    ->record();
```

```php
// Get total logins for a user
$totalLogins = $user->metrics()
    ->where('name', 'auth:logins')
    ->sum('value');

// Get orders this month for a customer
$ordersThisMonth = $customer->metrics()
    ->where('name', 'orders')
    ->thisMonth()
    ->sum('value');
```
Tokens:
Raw