Create Model for Term Of Use acceptance (#977)

* Create Model for Term Of Use acceptance

* minor fix

* Add missing Migration for tou_acceptances table

* add lastest() method to get lastest version of ToU

* Add test case

* Add test for ToU acceptance when user was created

* Fix test

* fix linting errors

* fix linting errors

* fix linting errors

* Fix typo in classes' names

* Add Job to generate 'tou_version' and 'tou_accepted_at' for existing users

* fix linting errors

* Change UserTermsOfUseAcceptances' relation with 'user_id'

* Minor fix

* fix UserTouAcceptanceJobTest

* fix linting error

* Refactor: Change TermsOfUseVersion from enum to Model

* Fix: Remove hard dependency on pre-seeded ToU version

* fix linting errors

* fix linting error

* minor changes

* Fix: removed unnecessary fields

* fix testing wrong version

* fix linting error

* rename the method that retrieve latest active version of ToU

Author: dati18

app/Jobs/CreateFirstTermsOfUseVersionJob.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Jobs;
+
+use App\TermsOfUseVersion;
+use Illuminate\Bus\Batchable;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Support\Facades\Log;
+use Throwable;
+
+class CreateFirstTermsOfUseVersionJob extends Job {
+    use Batchable;
+    use Dispatchable;
+
+    public function handle(): void {
+        try {
+            TermsOfUseVersion::create([
+                'version' => '2022-01-01',
+                'active' => true,
+            ]);
+        } catch (Throwable $exception) {
+            Log::error("Failure creating initial Terms of Use version: {$exception->getMessage()}");
+            $this->fail($exception);
+        }
+    }
+}

app/Jobs/UserCreateJob.php

@@ -2,8 +2,11 @@
 
 namespace App\Jobs;
 
+use App\TermsOfUseVersion;
 use App\User;
+use App\UserTermsOfUseAcceptance;
 use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\Log;
 
 class UserCreateJob extends Job {
     private $email;
@@ -30,6 +33,17 @@ public function handle() {
             'verified' => $this->verified,
         ]);
 
+        $latest = TermsOfUseVersion::latestActiveVersion();
+        if ($latest) {
+            UserTermsOfUseAcceptance::create([
+                'user_id' => $user->id,
+                'tou_version' => $latest->version,
+                'tou_accepted_at' => now(),
+            ]);
+        } else {
+            Log::warning("No active Terms of Use version found when creating user {$user->email} (ID {$user->id}).");
+        }
+
         return $user;
     }
 }

app/Jobs/UserTouAcceptanceJob.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Jobs;
+
+use App\TermsOfUseVersion;
+use App\User;
+use App\UserTermsOfUseAcceptance;
+use Illuminate\Bus\Batchable;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Support\Facades\Log;
+use Throwable;
+
+/**
+ * Bug: T401165 https://phabricator.wikimedia.org/T401165
+ * Job to record Terms of Use acceptance for all preexisting users.
+ * This job should only be run ONCE to seed the data for terms of use users have agreed to before we started tracking it explicitly.
+ * This job iterates through all users and creates a UserTermsOfUseAcceptance record
+ *  for each, using the latest (only) Terms of Use version and the user's creation date as ToU acceptance date.
+ * Errors during processing are logged and the job is marked as failed if accepting the terms of use for any user fails.
+ */
+class UserTouAcceptanceJob extends Job {
+    use Batchable;
+    use Dispatchable;
+
+    public function handle(): void {
+        $users = User::all();
+        foreach ($users as $user) {
+            try {
+                UserTermsOfUseAcceptance::create([
+                    'user_id' => $user->id,
+                    'tou_version' => TermsOfUseVersion::latestActiveVersion()->version,
+                    'tou_accepted_at' => $user->created_at,
+                ]);
+            } catch (Throwable $exception) {
+                Log::error("Failure processing user {$user->email} for UserTouAcceptanceJob: {$exception->getMessage()}");
+                $this->fail($exception);
+            }
+        }
+    }
+}

app/TermsOfUseVersion.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Bug: T401165 https://phabricator.wikimedia.org/T401165
+ * Be mindful that multiple ToU versions may exist over time,
+ * but only one should be active at a time.
+ */
+class TermsOfUseVersion extends Model {
+    use HasFactory;
+
+    protected $table = 'tou_versions';
+
+    const FIELDS = [
+        'version',
+        'active',
+    ];
+
+    protected $fillable = self::FIELDS;
+
+    protected $visible = self::FIELDS;
+
+    protected $casts = [
+        'version' => 'string',
+        'active' => 'boolean',
+    ];
+
+    public static function latestActiveVersion(): ?self {
+        return self::query()->where('active', true)->latest()->first();
+    }
+}

app/User.php

@@ -98,6 +98,10 @@ public function managesWikis(): \Illuminate\Database\Eloquent\Relations\BelongsT
         return $this->belongsToMany(Wiki::class, 'wiki_managers');
     }
 
+    public function touAcceptances(): \Illuminate\Database\Eloquent\Relations\HasMany {
+        return $this->hasMany(UserTermsOfUseAcceptance::class, 'user_id');
+    }
+
     public function hasVerifiedEmail() {
         return (bool) $this->verified;
     }

app/UserTermsOfUseAcceptance.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class UserTermsOfUseAcceptance extends Model {
+    use HasFactory;
+
+    public const FIELDS = [
+        'user_id',
+        'tou_version',
+        'tou_accepted_at',
+    ];
+
+    protected $fillable = self::FIELDS;
+
+    protected $visible = self::FIELDS;
+
+    protected $casts = [
+        'tou_version' => 'string',
+        'tou_accepted_at' => 'datetime',
+    ];
+
+    protected $table = 'tou_acceptances';
+
+    public function user(): BelongsTo {
+        return $this->belongsTo(User::class);
+    }
+}

database/migrations/2025_09_29_194758_tou_acceptances.php

@@ -0,0 +1,29 @@
+<?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('tou_acceptances', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedInteger('user_id');
+            $table->string('tou_version', 10);
+            $table->timestamp('tou_accepted_at');
+            $table->timestamps();
+            $table->unique(['user_id', 'tou_version']);
+            $table->foreign('user_id')->references('id')->on('users')->cascadeOnDelete();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void {
+        Schema::dropIfExists('tou_acceptances');
+    }
+};

database/migrations/2025_10_14_091126_tou_versions.php

@@ -0,0 +1,26 @@
+<?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('tou_versions', function (Blueprint $table) {
+            $table->id();
+            $table->string('version')->unique();
+            $table->boolean('active')->default(false);
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void {
+        Schema::dropIfExists('tou_versions');
+    }
+};

tests/Jobs/CreateFirstTermsOfUseVersionJobTest.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Tests\Jobs;
+
+use App\Jobs\CreateFirstTermsOfUseVersionJob;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class CreateFirstTermsOfUseVersionJobTest extends TestCase {
+    use RefreshDatabase;
+
+    public function testCreateFirstTermsOfUseVersionJob(): void {
+        $this->assertDatabaseCount('tou_versions', 0);
+
+        (new CreateFirstTermsOfUseVersionJob)->handle();
+
+        $this->assertDatabaseHas('tou_versions', [
+            'version' => '2022-01-01',
+            'active' => true,
+        ]);
+    }
+}

tests/Jobs/UserTermsOfUseAcceptanceTest.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Tests\Jobs;
+
+use App\Jobs\CreateFirstTermsOfUseVersionJob;
+use App\Jobs\UserCreateJob;
+use App\TermsOfUseVersion;
+use App\UserTermsOfUseAcceptance;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class UserTermsOfUseAcceptanceTest extends TestCase {
+    use RefreshDatabase;
+
+    public function testUserCreationCreatesTouAcceptance(): void {
+        (new CreateFirstTermsOfUseVersionJob)->handle();
+        $email = 'test+' . uniqid('', true) . '@example.com';
+        $user = (new UserCreateJob($email, 'thisisapassword123', true))->handle();
+
+        $this->assertDatabaseHas('tou_acceptances', [
+            'user_id' => $user->id,
+            'tou_version' => TermsOfUseVersion::latestActiveVersion()->version,
+        ]);
+
+        $rows = UserTermsOfUseAcceptance::where('user_id', $user->id)->get();
+        $this->assertCount(1, $rows);
+        $acceptance = $rows->first();
+
+        $this->assertSame(TermsOfUseVersion::latestActiveVersion()->version, $acceptance->tou_version);
+        $this->assertNotNull($acceptance->tou_accepted_at);
+    }
+}