Merge pull request #7 from DirectoryTree/custom-attributes

Add support for extending/adding additional columns/attributes

Author: stevebauman

README.md

@@ -30,6 +30,7 @@ Track page views, API calls, user signups, or any other countable events.
   - [Recording with Categories](#recording-with-categories)
   - [Recording with Dates](#recording-with-dates)
   - [Recording for Models](#recording-for-models)
+  - [Recording with Custom Attributes](#recording-with-custom-attributes)
   - [Capturing & Committing](#capturing--committing)
   - [Querying Metrics](#querying-metrics)
 - [Testing](#testing)
@@ -254,6 +255,105 @@ $ordersThisMonth = $customer->metrics()
     ->sum('value');
 ```
 
+### Recording with Custom Attributes
+
+Store additional context with your metrics by adding custom attributes. This is useful for segmenting metrics by various dimensions like source, country, device type, or any other custom data.
+
+First, create a migration to add custom columns to the `metrics` table:
+
+```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();
+});
+```
+
+Then, use the `with()` method to record metrics with custom attributes:
+
+```php
+// Track page views with traffic source
+metric('page_views')
+    ->with(['source' => 'google'])
+    ->record();
+
+// Track conversions with multiple attributes
+metric('conversions')
+    ->with([
+        'source' => 'facebook',
+        'country' => 'US',
+        'device' => 'mobile',
+    ])
+    ->record();
+
+// Combine with other methods
+metric('api:requests')
+    ->category('users')
+    ->with(['client_id' => 'abc123'])
+    ->record();
+```
+
+Custom attributes are included in the metric's uniqueness check, meaning metrics with different attribute values are stored separately:
+
+```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
+```
+
+This allows you to segment and analyze metrics by any dimension:
+
+```php
+// Get page views by source
+$googleViews = Metric::where('name', 'page_views')
+    ->where('source', 'google')
+    ->sum('value');
+
+// Get conversions by country this month
+$conversions = Metric::thisMonth()
+    ->where('name', 'conversions')
+    ->get()
+    ->groupBy('country')
+    ->map->sum('value');
+
+// Get mobile vs desktop traffic
+$mobileViews = Metric::today()
+    ->where('name', 'page_views')
+    ->where('device', 'mobile')
+    ->sum('value');
+```
+
+You can also use custom attributes with the `MetricData` class:
+
+```php
+use DirectoryTree\Metrics\MetricData;
+use DirectoryTree\Metrics\Facades\Metrics;
+
+Metrics::record(new MetricData(
+    name: 'page_views',
+    additional: [
+        'source' => 'google',
+        'country' => 'US',
+    ]
+));
+```
+
+Or with the `PendingMetric` class:
+
+```php
+use DirectoryTree\Metrics\PendingMetric;
+
+PendingMetric::make('page_views')
+    ->with(['source' => 'google', 'country' => 'US'])
+    ->record();
+```
+
+> [!important]
+> Core metric attributes (`name`, `category`, `year`, `month`, `day`, `measurable_type`, `measurable_id`, `value`) cannot be overridden via custom attributes. They are protected and will always use the values set through their respective methods.
+
 ### Capturing & Committing
 
 For high-performance scenarios, you may capture metrics in memory and commit them in batches:

database/migrations/2025_09_28_131354_create_metrics_table.php

@@ -23,16 +23,6 @@ public function up(): void
             $table->timestamps();
 
             $table->index(['year', 'month', 'day']);
-
-            $table->unique([
-                'name',
-                'category',
-                'year',
-                'month',
-                'day',
-                'measurable_type',
-                'measurable_id',
-            ], 'metrics_unique');
         });
     }
 

src/DatabaseMetricManager.php

@@ -12,13 +12,30 @@ class DatabaseMetricManager implements MetricManager
      */
     protected bool $capturing = false;
 
+    /**
+     * The metric model to use.
+     *
+     * @var class-string<\Illuminate\Database\Eloquent\Model>
+     */
+    public static string $model = Metric::class;
+
     /**
      * Constructor.
      */
     public function __construct(
         protected MetricRepository $repository
     ) {}
 
+    /**
+     * Set the metric model to use.
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $model
+     */
+    public static function useModel(string $model): void
+    {
+        static::$model = $model;
+    }
+
     /**
      * {@inheritDoc}
      */

src/Jobs/RecordMetric.php

@@ -2,6 +2,7 @@
 
 namespace DirectoryTree\Metrics\Jobs;
 
+use DirectoryTree\Metrics\DatabaseMetricManager;
 use DirectoryTree\Metrics\Measurable;
 use DirectoryTree\Metrics\Metric;
 use Illuminate\Bus\Queueable;
@@ -19,7 +20,7 @@ class RecordMetric implements ShouldQueue
      */
     public function __construct(
         /** @var Collection<Measurable>|Measurable */
-        public Collection|Measurable $metrics,
+        public Collection|Measurable $metrics
     ) {}
 
     /**
@@ -38,9 +39,13 @@ public function handle(): void
             fn (Measurable $metric) => $metric->value()
         );
 
-        Metric::query()->getConnection()->transaction(
-            function (ConnectionInterface $connection) use ($metric, $value) {
-                $model = Metric::query()->firstOrCreate([
+        /** @var \Illuminate\Database\Eloquent\Model $model */
+        $model = new DatabaseMetricManager::$model;
+
+        $model->getConnection()->transaction(
+            function (ConnectionInterface $connection) use ($metric, $value, $model) {
+                $instance = $model->newQuery()->firstOrCreate([
+                    ...$metric->additional(),
                     'name' => $metric->name(),
                     'category' => $metric->category(),
                     'year' => $metric->year(),
@@ -50,7 +55,7 @@ function (ConnectionInterface $connection) use ($metric, $value) {
                     'measurable_id' => $metric->measurable()?->getKey(),
                 ], ['value' => 0]);
 
-                Metric::query()->whereKey($model->getKey())->update([
+                $model->newQuery()->whereKey($instance->getKey())->update([
                     'value' => $connection->raw('value + '.$value),
                 ]);
             }

src/JsonMeasurableEncoder.php

@@ -23,6 +23,7 @@ public function encode(Measurable $metric): string
             'measurable' => $model ? get_class($model) : null,
             'measurable_key' => $model?->getKeyName() ?? null,
             'measurable_id' => $model?->getKey() ?? null,
+            'additional' => $metric->additional(),
         ]);
     }
 
@@ -53,7 +54,8 @@ public function decode(string $key, int $value): Measurable
             category: $attributes['category'],
             value: $value,
             date: $date,
-            measurable: $model
+            measurable: $model,
+            additional: $attributes['additional'] ?? [],
         );
     }
 }

src/Measurable.php

@@ -41,4 +41,9 @@ public function day(): int;
      * Get the measurable model of the metric.
      */
     public function measurable(): ?Model;
+
+    /**
+     * Get the additional attributes of the metric.
+     */
+    public function additional(): array;
 }

src/MetricData.php

@@ -21,6 +21,7 @@ public function __construct(
         protected int $value = 1,
         protected ?CarbonInterface $date = null,
         protected ?Model $measurable = null,
+        protected array $additional = [],
     ) {
         $this->date ??= new CarbonImmutable;
     }
@@ -80,4 +81,12 @@ public function measurable(): ?Model
     {
         return $this->measurable;
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function additional(): array
+    {
+        return $this->additional;
+    }
 }

src/PendingMetric.php

@@ -28,6 +28,13 @@ class PendingMetric
      */
     protected ?Model $measurable = null;
 
+    /**
+     * Additional attributes to store with the metric.
+     *
+     * @var array<string, mixed>
+     */
+    protected array $additional = [];
+
     /**
      * Constructor.
      */
@@ -74,6 +81,18 @@ public function measurable(Model $measurable): self
         return $this;
     }
 
+    /**
+     * Set additional attributes to store with the metric.
+     *
+     * @param  array<string, mixed>  $attributes
+     */
+    public function with(array $attributes): self
+    {
+        $this->additional = $attributes;
+
+        return $this;
+    }
+
     /**
      * Record the metric.
      */
@@ -94,7 +113,8 @@ public function toMetricData(int $value): Measurable
             $this->category,
             $value,
             $this->date,
-            $this->measurable
+            $this->measurable,
+            $this->additional
         );
     }
 }

tests/Jobs/RecordMetricTest.php

@@ -5,6 +5,8 @@
 use DirectoryTree\Metrics\Metric;
 use DirectoryTree\Metrics\MetricData;
 use DirectoryTree\Metrics\Tests\User;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
 
 it('can record a single metric', function () {
     $metric = new MetricData('page_views');
@@ -224,3 +226,50 @@
 
     expect($updated->updated_at->isAfter($originalUpdatedAt))->toBeTrue();
 });
+
+it('creates metrics with additional attributes', function () {
+    Schema::table('metrics', function (Blueprint $table) {
+        $table->string('source')->nullable();
+        $table->string('country')->nullable();
+    });
+
+    $data = new MetricData('page_views', additional: [
+        'source' => 'google',
+        'country' => 'US',
+    ]);
+
+    (new RecordMetric($data))->handle();
+    (new RecordMetric($data))->handle();
+
+    $metric = Metric::first();
+
+    expect($metric->source)->toBe('google');
+    expect($metric->country)->toBe('US');
+    expect($metric->value)->toBe(2);
+});
+
+it('cannot override core attributes with additional attributes', function () {
+    $data = new MetricData('page_views', additional: [
+        'name' => 'api_calls',
+        'category' => 'marketing',
+        'year' => 2025,
+        'month' => 1,
+        'day' => 1,
+        'measurable_type' => 'App\Models\User',
+        'measurable_id' => 1,
+        'value' => 100,
+    ]);
+
+    (new RecordMetric($data))->handle();
+
+    $recorded = Metric::first();
+
+    expect($recorded->name)->toBe('page_views')
+        ->and($recorded->category)->toBeNull()
+        ->and($recorded->year)->toBe(today()->year)
+        ->and($recorded->month)->toBe(today()->month)
+        ->and($recorded->day)->toBe(today()->day)
+        ->and($recorded->measurable_type)->toBeNull()
+        ->and($recorded->measurable_id)->toBeNull()
+        ->and($recorded->value)->toBe(1);
+});