storing analytics data

app/Models/ActivityEvent.php

@@ -0,0 +1,93 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * Unified activity feed event.
+ *
+ * Types: upload | comment | favorite | award | follow
+ * target_type: artwork | user
+ *
+ * @property int    $id
+ * @property int    $actor_id
+ * @property string $type
+ * @property string $target_type
+ * @property int    $target_id
+ * @property array|null $meta
+ * @property \Illuminate\Support\Carbon $created_at
+ */
+class ActivityEvent extends Model
+{
+    protected $table = 'activity_events';
+
+    public $timestamps = false;
+
+    const CREATED_AT = 'created_at';
+    const UPDATED_AT = null;
+
+    protected $fillable = [
+        'actor_id',
+        'type',
+        'target_type',
+        'target_id',
+        'meta',
+    ];
+
+    protected $casts = [
+        'actor_id'   => 'integer',
+        'target_id'  => 'integer',
+        'meta'       => 'array',
+        'created_at' => 'datetime',
+    ];
+
+    // ── Event type constants ──────────────────────────────────────────────────
+
+    const TYPE_UPLOAD   = 'upload';
+    const TYPE_COMMENT  = 'comment';
+    const TYPE_FAVORITE = 'favorite';
+    const TYPE_AWARD    = 'award';
+    const TYPE_FOLLOW   = 'follow';
+
+    const TARGET_ARTWORK = 'artwork';
+    const TARGET_USER    = 'user';
+
+    // ── Relations ─────────────────────────────────────────────────────────────
+
+    /** The user who performed the action */
+    public function actor(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'actor_id');
+    }
+
+    // ── Factory helpers ───────────────────────────────────────────────────────
+
+    public static function record(
+        int    $actorId,
+        string $type,
+        string $targetType,
+        int    $targetId,
+        array  $meta = []
+    ): static {
+        $event = static::create([
+            'actor_id'    => $actorId,
+            'type'        => $type,
+            'target_type' => $targetType,
+            'target_id'   => $targetId,
+            'meta'        => $meta ?: null,
+            'created_at'  => now(),
+        ]);
+
+        // Ensure created_at is available on the returned instance
+        // ($timestamps = false means Eloquent doesn't auto-populate it)
+        if ($event->created_at === null) {
+            $event->created_at = now();
+        }
+
+        return $event;
+    }
+}