♻️ rename trainDistance and trainDuration to totalDistance and …

…`totalDuration` (#2625)
Traewelling · May 30, 2024 · f7a62ee · f7a62ee
1 parent 5a11b0f
commit f7a62ee
Show file tree

Hide file tree

Showing 14 changed files with 243 additions and 531 deletions.
diff --git a/API_CHANGELOG.md b/API_CHANGELOG.md
@@ -6,6 +6,13 @@ This is to help you keep track of the changes and to help you update your code a
 
 ## 2024-05-30
 
+Renamed `trainDuration` and `trainDistance` attributes to `totalDuration` and `totalDistance` in all `User` object.
+(We have more than just trains.)
+
+The old attributes will be removed after 2024-08.
+
+## 2024-05-30
+
 Deprecated `GET /activeEvents` endpoint, which will be removed after 2024-08.
 
 Change behavior of `GET /events` endpoint:

diff --git a/app/Http/Controllers/API/v1/AuthController.php b/app/Http/Controllers/API/v1/AuthController.php
@@ -2,7 +2,7 @@
 
 namespace App\Http\Controllers\API\v1;
 
-use App\Http\Resources\UserSettingsResource;
+use App\Http\Resources\UserAuthResource;
 use App\Providers\AuthServiceProvider;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -56,7 +56,7 @@ public function logout(Request $request): JsonResponse {
      *          description="successful operation",
      *          @OA\JsonContent(
      *              @OA\Property(property="data", type="object",
-     *                      ref="#/components/schemas/UserAuth"
+     *                      ref="#/components/schemas/UserAuthResource"
      *              )
      *          )
      *       ),
@@ -69,11 +69,11 @@ public function logout(Request $request): JsonResponse {
      *
      * @param Request $request
      *
-     * @return JsonResponse
+     * @return UserAuthResource
      * @api v1
      */
-    public function user(Request $request): JsonResponse {
-        return $this->sendResponse(new UserSettingsResource($request->user()));
+    public function user(Request $request) {
+        return new UserAuthResource($request->user());
     }
 
     /**

diff --git a/app/Http/Controllers/API/v1/StatisticsController.php b/app/Http/Controllers/API/v1/StatisticsController.php
@@ -35,7 +35,7 @@ class StatisticsController extends Controller
      *          @OA\JsonContent(
      *              @OA\Property(property="data", type="array",
      *                  @OA\Items(
-     *                      ref="#/components/schemas/LeaderboardUser"
+     *                      ref="#/components/schemas/LeaderboardUserResource"
      *                  )
      *              ),
      *          )
@@ -44,7 +44,6 @@ class StatisticsController extends Controller
      *       @OA\Response(response=404, description="No Event found for this id"),
      *       security={
      *           {"passport": {"read-statistics"}}, {"token": {}}
-     *
      *       }
      *     )
      *
@@ -66,7 +65,7 @@ public function leaderboard(): AnonymousResourceCollection {
      *          @OA\JsonContent(
      *              @OA\Property(property="data", type="array",
      *                  @OA\Items(
-     *                      ref="#/components/schemas/LeaderboardUser"
+     *                      ref="#/components/schemas/LeaderboardUserResource"
      *                  )
      *              ),
      *          )
@@ -98,7 +97,7 @@ public function leaderboardByDistance(): AnonymousResourceCollection {
      *          @OA\JsonContent(
      *              @OA\Property(property="data", type="array",
      *                  @OA\Items(
-     *                      ref="#/components/schemas/LeaderboardUser"
+     *                      ref="#/components/schemas/LeaderboardUserResource"
      *                  )
      *              ),
      *          )
@@ -136,7 +135,7 @@ public function leaderboardFriends(): AnonymousResourceCollection {
      *          @OA\JsonContent(
      *              @OA\Property(property="data", type="array",
      *                  @OA\Items(
-     *                      ref="#/components/schemas/LeaderboardUser"
+     *                      ref="#/components/schemas/LeaderboardUserResource"
      *                  )
      *              ),
      *          )

diff --git a/app/Http/Controllers/API/v1/TransportController.php b/app/Http/Controllers/API/v1/TransportController.php
@@ -76,14 +76,14 @@ public function getLegacyDepartures(Request $request, string $name): JsonRespons
      *         description="Träwelling-ID of the station (you can look this up with
      *         [trainStationAutocomplete](#/Checkin/trainStationAutocomplete))", required=true,
      *     ),
-     *     @OA\Parameter(
+     * @OA\Parameter(
      *         name="when",
      *         in="query",
      *         description="When to get the departures (default: now).
-    If you omit the timezone, the datetime is interpreted as localtime.
-    This is especially helpful when träwelling abroad.",
+     * If you omit the timezone, the datetime is interpreted as localtime.
+     * This is especially helpful when träwelling abroad.",
      *         required=false,
-     *         @OA\Schema(
+     * @OA\Schema(
      *             type="string",
      *             format="date-time",
      *             example="2020-01-01T12:00:00.000Z"
@@ -552,7 +552,7 @@ public function setHome(int $stationId): JsonResponse {
      *          @OA\JsonContent(
      *              @OA\Property(property="data", type="array",
      *                  @OA\Items(
-     *                      ref="#/components/schemas/AutocompleteStation"
+     *                      ref="#/components/schemas/StationResource"
      *                  )
      *              )
      *          )

diff --git a/app/Http/Controllers/TransportController.php b/app/Http/Controllers/TransportController.php
@@ -5,6 +5,7 @@
 use App\Enum\TravelType;
 use App\Exceptions\HafasException;
 use App\Http\Controllers\Backend\Transport\StationController;
+use App\Http\Resources\StationResource;
 use App\Models\Checkin;
 use App\Models\PolyLine;
 use App\Models\Station;
@@ -36,12 +37,7 @@ public static function getTrainStationAutocomplete(string $query): Collection {
         }
 
         return $stations->map(function(Station $station) {
-            return [
-                'id'            => $station->id,
-                'ibnr'          => $station->ibnr,
-                'rilIdentifier' => $station->rilIdentifier,
-                'name'          => $station->name
-            ];
+            return new StationResource($station);
         });
     }
 

diff --git a/app/Http/Resources/LeaderboardUserResource.php b/app/Http/Resources/LeaderboardUserResource.php
@@ -5,14 +5,26 @@
 use App\Http\Controllers\Backend\User\ProfilePictureController;
 use Illuminate\Http\Resources\Json\JsonResource;
 
+/**
+ * @OA\Schema(
+ *      title="LeaderboardUserResource",
+ *      @OA\Property(property="username", type="string", description="username of user", example="Gertrud123"),
+ *      @OA\Property(property="profilePicture", type="string", description="URL of the profile picture of the user", example="https://traewelling.de/@Gertrud123/picture"),
+ *      @OA\Property(property="totalDuration", type="integer", description="duration travelled in minutes", example=6),
+ *      @OA\Property(property="totalDistance", type="integer", description="distance travelled in meters", example=12345),
+ *      @OA\Property(property="points", type="integer", description="points of user")
+ * )
+ */
 class LeaderboardUserResource extends JsonResource
 {
     public function toArray($request): array {
         return [
             'username'       => $this->user->username,
             'profilePicture' => ProfilePictureController::getUrl($this->user),
-            'trainDuration'  => (int) $this->duration, // @todo: rename key - we have more than just trains
-            'trainDistance'  => (float) $this->distance, // @todo: rename key - we have more than just trains
+            'trainDuration'  => (int) $this->duration, // @deprecated: remove after 2024-08
+            'trainDistance'  => (float) $this->distance, // @deprecated: remove after 2024-08
+            'totalDuration'  => (int) $this->duration,
+            'totalDistance'  => (float) $this->distance,
             'points'         => (int) $this->points
         ];
     }

diff --git a/app/Http/Resources/StationResource.php b/app/Http/Resources/StationResource.php
@@ -4,6 +4,17 @@
 
 use Illuminate\Http\Resources\Json\JsonResource;
 
+/**
+ * @OA\Schema(
+ *     title="Station",
+ *     @OA\Property(property="id", type="integer", example="1"),
+ *     @OA\Property(property="name", type="string", example="Karlsruhe Hbf"),
+ *     @OA\Property(property="latitude", type="number", example="48.993207"),
+ *     @OA\Property(property="longitude", type="number", example="8.400977"),
+ *     @OA\Property(property="ibnr", type="string", example="8000191"),
+ *     @OA\Property(property="rilIdentifier", type="string", example="RK")
+ * )
+ */
 class StationResource extends JsonResource
 {
     public function toArray($request): array {

diff --git a/app/Http/Resources/UserAuthResource.php b/app/Http/Resources/UserAuthResource.php
@@ -0,0 +1,51 @@
+<?php
+
+namespace App\Http\Resources;
+
+use App\Http\Controllers\Backend\User\ProfilePictureController;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * @OA\Schema(
+ *      title="UserAuth",
+ *      @OA\Property(property="id", type="integer", example="1"),
+ *      @OA\Property(property="displayName", type="string", example="Gertrud"),
+ *      @OA\Property(property="username", type="string", example="Gertrud123"),
+ *      @OA\Property(property="profilePicture", type="string", example="https://traewelling.de/@Gertrud123/picture"),
+ *      @OA\Property(property="totalDistance", type="integer", example="100"),
+ *      @OA\Property(property="totalDuration", type="integer", example="100"),
+ *      @OA\Property(property="points", type="integer", example="100"),
+ *      @OA\Property(property="mastodonUrl", type="string", example="https://mastodon.social/@Gertrud123", nullable=true),
+ *      @OA\Property(property="privateProfile", type="boolean", example="false"),
+ *      @OA\Property(property="preventIndex", type="boolean", example="false"),
+ *      @OA\Property(property="likes_enabled", type="boolean", example="true"),
+ *      @OA\Property(property="home", type="object", ref="#/components/schemas/StationResource"),
+ *      @OA\Property(property="language", type="string", example="de"),
+ *      @OA\Property(property="defaultStatusVisibility", type="integer", example=0),
+ *      @OA\Property(property="roles", type="array", @OA\Items(type="string"), example={"admin", "open-beta", "closed-beta"})
+ * )
+ */
+class UserAuthResource extends JsonResource
+{
+    public function toArray($request): array {
+        return [
+            'id'                      => (int) $this->id,
+            'displayName'             => (string) $this->name,
+            'username'                => (string) $this->username,
+            'profilePicture'          => ProfilePictureController::getUrlForUserId($this->id),
+            'trainDistance'           => (float) $this->train_distance, // @deprecated: remove after 2024-08
+            'totalDistance'           => (float) $this->train_distance,
+            'trainDuration'           => (int) $this->train_duration, // @deprecated: remove after 2024-08
+            'totalDuration'           => (int) $this->train_duration,
+            'points'                  => (int) $this->points,
+            'mastodonUrl'             => $this->mastodonUrl ?? null,
+            'privateProfile'          => (bool) $this->private_profile,
+            'preventIndex'            => $this->prevent_index,
+            'likes_enabled'           => $this->likes_enabled,
+            'home'                    => new StationResource($this->home),
+            'language'                => $this->language,
+            'defaultStatusVisibility' => $this->default_status_visibility,
+            'roles'                   => $this->roles->pluck('name')
+        ];
+    }
+}
diff --git a/app/Http/Resources/UserBaseResource.php b/app/Http/Resources/UserBaseResource.php
@@ -4,26 +4,20 @@
 
 use App\Http\Controllers\Backend\User\ProfilePictureController;
 use App\Models\User;
-use Illuminate\Http\Request;
 use Illuminate\Http\Resources\Json\JsonResource;
 
 class UserBaseResource extends JsonResource
 {
-    /**
-     * Transform the resource into an array.
-     *
-     * @param Request $request
-     *
-     * @return array
-     */
     public function toArray($request): array {
         return [
             'id'             => (int) $this->id,
             'displayName'    => (string) $this->name,
             'username'       => (string) $this->username,
             'profilePicture' => ProfilePictureController::getUrlForUserId($this->id),
-            'trainDistance'  => (float) $this->train_distance, // @todo: rename key - we have more than just trains
-            'trainDuration'  => (int) $this->train_duration, // @todo: rename key - we have more than just trains
+            'trainDistance'  => (float) $this->train_distance, // @deprecated: remove after 2024-08
+            'totalDistance'  => (float) $this->train_distance,
+            'trainDuration'  => (int) $this->train_duration, // @deprecated: remove after 2024-08
+            'totalDuration'  => (int) $this->train_duration,
             'points'         => (int) $this->points,
             'mastodonUrl'    => $this->mastodonUrl ?? null,
             'privateProfile' => (bool) $this->private_profile,
@@ -41,7 +35,7 @@ public function toArray($request): array {
                     'muted'             => (bool) $this->muted,
                     'following'         => (bool) $this->following,
                     'followPending'     => (bool) $this->followPending,
-                ]),
+                ])
         ];
     }
 }
diff --git a/app/Virtual/Models/AutocompleteStation.php b/app/Virtual/Models/AutocompleteStation.php