From 461ac7f0f6b7ef9a2413202ddac461edfbc2693b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Lup=C4=8D=C3=ADk?= <shawnczek@truckersmp.com>
Date: Tue, 21 Jan 2025 11:18:01 +0100
Subject: [PATCH] Clarify the active state and admin fields in the Ban model.

---
 src/Models/Ban.php | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/src/Models/Ban.php b/src/Models/Ban.php
index 8305bdd..1611a4e 100644
--- a/src/Models/Ban.php
+++ b/src/Models/Ban.php
@@ -22,7 +22,12 @@ class Ban extends Model
     protected Carbon $timeAdded;
 
     /**
-     * If the ban is still active.
+     * If the ban is still active or was disabled.
+     *
+     * When a ban was issued by mistake, staff may deactivate it manually, but
+     * it still shows as inactive in the ban history.
+     *
+     * Does not change if the ban expires naturally on the expiration date.
      *
      * @var bool
      */
@@ -38,6 +43,8 @@ class Ban extends Model
     /**
      * The name of the admin that banned the user.
      *
+     * This field is generally redacted when accessing the public API.
+     *
      * @var string
      */
     protected string $adminName;
@@ -45,6 +52,8 @@ class Ban extends Model
     /**
      * The TruckersMP ID for the admin that banned the user.
      *
+     * This field is generally redacted when accessing the public API.
+     *
      * @var int
      */
     protected int $adminId;
@@ -98,7 +107,12 @@ public function getCreatedAt(): Carbon
     }
 
     /**
-     * Determine if the ban is active or not.
+     * Determine if the ban is active or was disabled.
+     *
+     * When a ban was issued by mistake, staff may deactivate it manually, but
+     * it still shows as inactive in the ban history.
+     *
+     * Does not change if the ban expires naturally on the expiration date.
      *
      * @return bool
      */
@@ -120,6 +134,8 @@ public function getReason(): string
     /**
      * Get the name of the admin who banned the player.
      *
+     * This field is generally redacted when accessing the public API.
+     *
      * @return string
      */
     public function getAdminName(): string
@@ -130,6 +146,8 @@ public function getAdminName(): string
     /**
      * Get the TMP ID of the admin who banned the player.
      *
+     * This field is generally redacted when accessing the public API.
+     *
      * @return int
      */
     public function getAdminId(): int