feat: media play

app/Http/Controllers/MediaController.php

@@ -3,6 +3,7 @@
 namespace App\Http\Controllers;
 
 use App\Models\Media;
+use App\Models\MediaPlay;
 use App\Models\Category;
 use App\Models\SubCategory;
 use App\Models\Tag;
@@ -567,6 +568,76 @@ public function saved()
         return auth()->user()->savedMedia()->with(['image','categories', 'subCategories', 'myNote' , 'tags'])->get();
     }
 
+    // RECORD a play for the current user (feeds popular + recently played).
+    public function recordPlay($id)
+    {
+        $media = Media::where('id', $id)
+            ->where(function ($q) {
+                $q->where('visibility', 'public')->orWhere('user_id', auth()->id());
+            })
+            ->firstOrFail();
+
+        $play = MediaPlay::firstOrNew([
+            'user_id' => auth()->id(),
+            'media_id' => $media->id,
+        ]);
+        $play->play_count = ($play->play_count ?? 0) + 1;
+        $play->last_played_at = now();
+        $play->save();
+
+        return response()->json([
+            'message' => 'Play recorded',
+            'play_count' => $play->play_count,
+            'last_played_at' => $play->last_played_at,
+        ]);
+    }
+
+    // POPULAR media (global), ranked by total play count across all users.
+    public function popular(Request $request)
+    {
+        $limit = (int) $request->input('limit', 20);
+
+        $media = Media::query()
+            ->where(function ($q) {
+                $q->where('visibility', 'public')->orWhere('user_id', auth()->id());
+            })
+            ->withCount('plays as listeners_count')                 // distinct users who played
+            ->withSum('plays as plays_count', 'play_count')         // total plays
+            ->with(['image', 'categories', 'subCategories', 'tags'])
+            ->orderByDesc('plays_count')
+            ->orderByDesc('listeners_count')
+            ->orderByDesc('created_at')
+            ->limit($limit)
+            ->get();
+
+        return response()->json($media);
+    }
+
+    // RECENTLY PLAYED media for the current user, most recent first.
+    public function recentlyPlayed(Request $request)
+    {
+        $limit = (int) $request->input('limit', 20);
+
+        $plays = MediaPlay::where('user_id', auth()->id())
+            ->whereNotNull('last_played_at')
+            ->with(['media' => fn ($q) => $q->with(['image', 'categories', 'subCategories', 'tags'])])
+            ->orderByDesc('last_played_at')
+            ->limit($limit)
+            ->get();
+
+        $media = $plays->map(function ($play) {
+            $media = $play->media;
+            if (!$media) {
+                return null;
+            }
+            $media->last_played_at = $play->last_played_at;
+            $media->play_count = $play->play_count;
+            return $media;
+        })->filter()->values();
+
+        return response()->json($media);
+    }
+
 public function storeNote(Request $request, $mediaId)
 {
     $media = Media::findOrFail($mediaId);

app/Http/Controllers/SurveyQuestionController.php

@@ -2,7 +2,10 @@
 
 namespace App\Http\Controllers;
 
+use App\Models\Media;
+use App\Models\SurveyAnswer;
 use App\Models\SurveyQuestion;
+use App\Models\Tag;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Validation\ValidationException;
@@ -12,7 +15,7 @@ class SurveyQuestionController extends Controller
     // USER: list active questions with their options and the current user's own answers.
     public function index(Request $request)
     {
-        $questions = SurveyQuestion::with(['options', 'userAnswers'])
+        $questions = SurveyQuestion::with(['options.tags', 'userAnswers'])
             ->where('is_active', true)
             ->orderBy('order')
             ->get();
@@ -23,7 +26,7 @@ public function index(Request $request)
     // USER: a single question with its options and the current user's own answers.
     public function show($id)
     {
-        $question = SurveyQuestion::with(['options', 'userAnswers'])->findOrFail($id);
+        $question = SurveyQuestion::with(['options.tags', 'userAnswers'])->findOrFail($id);
 
         return response()->json($question);
     }
@@ -32,7 +35,7 @@ public function show($id)
     public function adminIndex(Request $request)
     {
         $questions = SurveyQuestion::with([
-                'options' => fn ($q) => $q->withCount('answers'),
+                'options' => fn ($q) => $q->withCount('answers')->with('tags'),
                 'answers' => fn ($q) => $q->with(['user', 'option']),
             ])
             ->orderBy('order')
@@ -45,7 +48,7 @@ public function adminIndex(Request $request)
     public function adminShow($id)
     {
         $question = SurveyQuestion::with([
-                'options' => fn ($q) => $q->withCount('answers'),
+                'options' => fn ($q) => $q->withCount('answers')->with('tags'),
                 'answers' => fn ($q) => $q->with(['user', 'option']),
             ])
             ->findOrFail($id);
@@ -113,6 +116,8 @@ public function store(Request $request)
             'options.*.label' => 'required|string|max:255',
             'options.*.value' => 'nullable|string|max:255',
             'options.*.order' => 'nullable|integer',
+            'options.*.tags' => 'nullable|array',
+            'options.*.tags.*' => 'string',
         ]);
 
         $question = DB::transaction(function () use ($data) {
@@ -131,7 +136,7 @@ public function store(Request $request)
 
         return response()->json([
             'message' => 'Question created successfully',
-            'question' => $question->load('options'),
+            'question' => $question->load('options.tags'),
         ], 201);
     }
 
@@ -150,6 +155,8 @@ public function update(Request $request, $id)
             'options.*.label' => 'required_with:options|string|max:255',
             'options.*.value' => 'nullable|string|max:255',
             'options.*.order' => 'nullable|integer',
+            'options.*.tags' => 'nullable|array',
+            'options.*.tags.*' => 'string',
         ]);
 
         DB::transaction(function () use ($question, $data) {
@@ -174,7 +181,7 @@ public function update(Request $request, $id)
 
         return response()->json([
             'message' => 'Question updated successfully',
-            'question' => $question->load('options'),
+            'question' => $question->load('options.tags'),
         ]);
     }
 
@@ -236,14 +243,63 @@ public function answer(Request $request, $id)
         ]);
     }
 
+    // USER: suggest media based on the tags attached to the options this user has chosen.
+    public function suggestedMedia(Request $request)
+    {
+        $userId = auth()->id();
+
+        $answersQuery = SurveyAnswer::where('user_id', $userId);
+        if ($request->filled('question_id')) {
+            $answersQuery->where('survey_question_id', $request->question_id);
+        }
+        $optionIds = $answersQuery->pluck('survey_option_id');
+
+        if ($optionIds->isEmpty()) {
+            return response()->json([]);
+        }
+
+        // Collect the tags behind the chosen options.
+        $tagIds = DB::table('survey_option_tag')
+            ->whereIn('survey_option_id', $optionIds)
+            ->pluck('tag_id')
+            ->unique()
+            ->values();
+
+        if ($tagIds->isEmpty()) {
+            return response()->json([]);
+        }
+
+        // Media sharing those tags, ranked by how many of them match.
+        $media = Media::query()
+            ->whereHas('tags', fn ($q) => $q->whereIn('tags.id', $tagIds))
+            ->withCount(['tags as match_count' => fn ($q) => $q->whereIn('tags.id', $tagIds)])
+            ->where(function ($q) use ($userId) {
+                $q->where('visibility', 'public')->orWhere('user_id', $userId);
+            })
+            ->with(['image', 'categories', 'subCategories', 'tags'])
+            ->orderByDesc('match_count')
+            ->orderByDesc('created_at')
+            ->get();
+
+        return response()->json($media);
+    }
+
     private function syncOptions(SurveyQuestion $question, array $options): void
     {
         foreach (array_values($options) as $i => $option) {
-            $question->options()->create([
+            $created = $question->options()->create([
                 'label' => $option['label'],
                 'value' => $option['value'] ?? null,
                 'order' => $option['order'] ?? $i,
             ]);
+
+            if (!empty($option['tags'])) {
+                $tagIds = collect($option['tags'])
+                    ->map(fn ($name) => Tag::firstOrCreate(['name' => $name])->id)
+                    ->all();
+
+                $created->tags()->sync($tagIds);
+            }
         }
     }
 }

app/Models/Media.php

@@ -56,6 +56,11 @@ public function tags()
     {
         return $this->belongsToMany(Tag::class, 'media_tag');
     }
+
+    public function plays()
+    {
+        return $this->hasMany(MediaPlay::class);
+    }
     public function notes()
     {
         return $this->morphMany(Note::class, 'noteable');

app/Models/MediaPlay.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class MediaPlay extends Model
+{
+    protected $fillable = ['user_id', 'media_id', 'play_count', 'last_played_at'];
+
+    protected $casts = [
+        'play_count' => 'integer',
+        'last_played_at' => 'datetime',
+    ];
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function media(): BelongsTo
+    {
+        return $this->belongsTo(Media::class);
+    }
+}

app/Models/SurveyOption.php

@@ -4,6 +4,7 @@
 
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 
 class SurveyOption extends Model
@@ -23,4 +24,10 @@ public function answers(): HasMany
     {
         return $this->hasMany(SurveyAnswer::class);
     }
+
+    // Tags used to suggest media when a user picks this option.
+    public function tags(): BelongsToMany
+    {
+        return $this->belongsToMany(Tag::class, 'survey_option_tag');
+    }
 }

database/migrations/2026_06_01_110000_create_survey_option_tag_table.php

@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('survey_option_tag', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('survey_option_id')->constrained('survey_options')->cascadeOnDelete();
+            $table->foreignId('tag_id')->constrained('tags')->cascadeOnDelete();
+            $table->timestamps();
+
+            $table->unique(['survey_option_id', 'tag_id']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('survey_option_tag');
+    }
+};

database/migrations/2026_06_01_120000_create_media_plays_table.php

@@ -0,0 +1,35 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('media_plays', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained('users')->cascadeOnDelete();
+            $table->foreignId('media_id')->constrained('media')->cascadeOnDelete();
+            $table->unsignedInteger('play_count')->default(0);
+            $table->timestamp('last_played_at')->nullable();
+            $table->timestamps();
+
+            // One row per user + media; updated on each play.
+            $table->unique(['user_id', 'media_id']);
+            $table->index('last_played_at');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('media_plays');
+    }
+};

routes/api.php

@@ -127,6 +127,7 @@
         Route::get('/admin/survey-questions/{id}', [SurveyQuestionController::class, 'adminShow']);
     });
     // User: answer + read questions with their own answers only.
+    Route::get('/survey-questions/suggested-media', [SurveyQuestionController::class, 'suggestedMedia']);
     Route::post('/survey-questions/{id}/answer', [SurveyQuestionController::class, 'answer']);
     Route::apiResource('survey-questions', SurveyQuestionController::class);
 
@@ -160,12 +161,15 @@
 
     ///media
     Route::get('/media/filters', [MediaController::class, 'filters']);
+    Route::get('/media/popular', [MediaController::class, 'popular']);
+    Route::get('/media/recently-played', [MediaController::class, 'recentlyPlayed']);
     Route::post('/media', [MediaController::class, 'store']);
     Route::get('/media', [MediaController::class, 'index']);
     Route::post('/media/{id}', [MediaController::class, 'update']);
     Route::get('/media/saved', [MediaController::class, 'saved']);
     Route::delete('/media/{id}', [MediaController::class, 'destroy']);
     Route::get('/media/{id}', [MediaController::class, 'show']);
+    Route::post('/media/{id}/play', [MediaController::class, 'recordPlay']);
     Route::post('/media/{id}/save', [MediaController::class, 'toggleSaveMedia']);
     Route::post('/media/{id}/rate', [MediaController::class, 'rate']);
     Route::post('/media/{id}/comment', [MediaController::class, 'storeComment']);