✨Feature: Allows random endpoints to return multiple items

app/Contracts/Repository.php

@@ -33,6 +33,4 @@ public function tableName(): string;
     public function scrape(int|string $id): array;
 
     public function insert(array $attributes): bool;
-
-    public function random(int $numberOfRandomItems = 1): Collection;
 }

app/Dto/Concerns/HasLimitParameter.php

@@ -13,6 +13,8 @@
  *  @OA\Parameter(
  *    name="limit",
  *    in="query",
+ *    required=false,
+ *    description="Maximum limit (and the default number of entries returned) is 25 for all endpoints except for Random endpoints where the maximum limit is 5 and the default number of entries returned is 1.",
  *    @OA\Schema(type="integer")
  *  ),
  */

app/Dto/Concerns/HasLimitParameterWithSmallerMax.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Dto\Concerns;
+
+use App\Rules\Attributes\MaxLimitWithFallback;
+use OpenApi\Annotations as OA;
+use Spatie\LaravelData\Attributes\Validation\IntegerType;
+use Spatie\LaravelData\Attributes\Validation\Min;
+use Spatie\LaravelData\Optional;
+
+trait HasLimitParameterWithSmallerMax
+{
+    use PreparesData;
+
+    #[IntegerType, Min(1), MaxLimitWithFallback(5)]
+    public int|Optional $limit;
+}

app/Dto/Concerns/PreparesData.php

@@ -16,10 +16,13 @@ trait PreparesData
     public static function prepareForPipeline(Collection $properties): Collection
     {
         // let's always set the limit parameter to the globally configured default value
-        if (property_exists(static::class, "limit") && !$properties->has("limit")) {
-            $properties->put("limit", max_results_per_page(
-                property_exists(static::class, "defaultLimit") ? static::$defaultLimit : null));
-        }
+        // // BUG: this causes override and always sets the default limit to config value
+        //         even if the property `limit` does not exist
+        //         max_results_per_page never accepts $defaultLimit and will always return config value
+        // if (property_exists(static::class, "limit") && !$properties->has("limit")) {
+        //     $properties->put("limit", max_results_per_page(
+        //         property_exists(static::class, "defaultLimit") ? static::$defaultLimit : null));
+        // }
 
         // we want to cast "true" and "false" string values to boolean before validation, so let's take all properties
         // of the class which are bool or bool|Optional type, and using their name read the values from the incoming

app/Dto/QueryRandomAnimeCommand.php

@@ -3,15 +3,19 @@
 namespace App\Dto;
 
 use App\Contracts\DataRequest;
+use App\Dto\Concerns\HasLimitParameterWithSmallerMax;
 use App\Dto\Concerns\HasSfwParameter;
 use App\Dto\Concerns\HasUnapprovedParameter;
+use App\Http\Resources\V4\AnimeCollection;
 use App\Http\Resources\V4\AnimeResource;
 use Spatie\LaravelData\Data;
 
 /**
- * @implements DataRequest<AnimeResource>
+ * @implements DataRequest<AnimeResource|AnimeCollection>
  */
 final class QueryRandomAnimeCommand extends Data implements DataRequest
 {
-    use HasSfwParameter, HasUnapprovedParameter;
+    use HasSfwParameter,
+        HasUnapprovedParameter,
+        HasLimitParameterWithSmallerMax;
 }

app/Dto/QueryRandomCharacterCommand.php

@@ -3,6 +3,7 @@
 namespace App\Dto;
 
 use App\Contracts\DataRequest;
+use App\Dto\Concerns\HasLimitParameterWithSmallerMax;
 use App\Http\Resources\V4\CharacterResource;
 use Spatie\LaravelData\Data;
 
@@ -11,4 +12,5 @@
  */
 final class QueryRandomCharacterCommand extends Data implements DataRequest
 {
+    use HasLimitParameterWithSmallerMax;
 }

app/Dto/QueryRandomMangaCommand.php

@@ -3,15 +3,19 @@
 namespace App\Dto;
 
 use App\Contracts\DataRequest;
+use App\Dto\Concerns\HasLimitParameterWithSmallerMax;
 use App\Dto\Concerns\HasSfwParameter;
 use App\Dto\Concerns\HasUnapprovedParameter;
+use App\Http\Resources\V4\MangaCollection;
 use App\Http\Resources\V4\MangaResource;
 use Spatie\LaravelData\Data;
 
 /**
- * @implements DataRequest<MangaResource>
+ * @implements DataRequest<MangaResource|MangaCollection>
  */
 final class QueryRandomMangaCommand extends Data implements DataRequest
 {
-    use HasSfwParameter, HasUnapprovedParameter;
+    use HasSfwParameter,
+        HasUnapprovedParameter,
+        HasLimitParameterWithSmallerMax;
 }

app/Dto/QueryRandomPersonCommand.php

@@ -3,12 +3,15 @@
 namespace App\Dto;
 
 use App\Contracts\DataRequest;
+use App\Dto\Concerns\HasLimitParameterWithSmallerMax;
+use App\Http\Resources\V4\PersonCollection;
 use App\Http\Resources\V4\PersonResource;
 use Spatie\LaravelData\Data;
 
 /**
- * @implements DataRequest<PersonResource>
+ * @implements DataRequest<PersonResource|PersonCollection>
  */
 final class QueryRandomPersonCommand extends Data implements DataRequest
 {
+    use HasLimitParameterWithSmallerMax;
 }

app/Dto/QueryRandomUserCommand.php

@@ -3,6 +3,7 @@
 namespace App\Dto;
 
 use App\Contracts\DataRequest;
+use App\Dto\Concerns\HasLimitParameterWithSmallerMax;
 use App\Http\Resources\V4\ProfileResource;
 use Spatie\LaravelData\Data;
 
@@ -11,4 +12,5 @@
  */
 final class QueryRandomUserCommand extends Data implements DataRequest
 {
+    use HasLimitParameterWithSmallerMax;
 }

app/Dto/QuerySpecificAnimeSeasonCommand.php

@@ -24,8 +24,6 @@ final class QuerySpecificAnimeSeasonCommand extends QueryAnimeSeasonCommand
     #[WithCast(EnumCast::class, AnimeSeasonEnum::class), EnumValidation(AnimeSeasonEnum::class)]
     public AnimeSeasonEnum $season;
 
-    protected static int $defaultLimit = 30;
-
     public static function messages(...$args): array
     {
         return [

app/Features/QueryRandomAnimeHandler.php

@@ -5,28 +5,31 @@
 use App\Anime;
 use App\Contracts\RequestHandler;
 use App\Dto\QueryRandomAnimeCommand;
+use App\Http\Resources\V4\AnimeCollection;
 use App\Http\Resources\V4\AnimeResource;
 use Spatie\LaravelData\Optional;
 
 /**
- * @implements RequestHandler<QueryRandomAnimeCommand, AnimeResource>
+ * @implements RequestHandler<QueryRandomAnimeCommand, AnimeResource|AnimeCollection>
  */
 final class QueryRandomAnimeHandler implements RequestHandler
 {
     /**
      * @inheritDoc
      */
-    public function handle($request): AnimeResource
+    public function handle($request): AnimeResource|AnimeCollection
     {
         $queryable = Anime::query();
 
-        $o = Optional::create();
-        $sfwParam = $request->sfw === $o ? false : $request->sfw;
-        $unapprovedParam = $request->unapproved === $o ? false : $request->unapproved;
+        $sfwParam = $request->sfw instanceof Optional ? false : $request->sfw;
+        $unapprovedParam = $request->unapproved instanceof Optional ? false : $request->unapproved;
+        $limit = $request->limit instanceof Optional ? 1 : $request->limit;
 
-        return new AnimeResource(
-            $queryable->random(1, $sfwParam, $unapprovedParam)->first()
-        );
+        $results = $queryable->random($limit, $sfwParam, $unapprovedParam);
+
+        return $results->count() === 1
+            ? new AnimeResource($results->first())
+            : new AnimeCollection($results, false);
     }
 
     /**

app/Features/QueryRandomCharacterHandler.php

@@ -2,20 +2,33 @@
 
 namespace App\Features;
 
-use App\Contracts\CharacterRepository;
+use App\Character;
+use App\Contracts\RequestHandler;
 use App\Dto\QueryRandomCharacterCommand;
+use App\Http\Resources\V4\CharacterCollection;
 use App\Http\Resources\V4\CharacterResource;
-use Illuminate\Http\Resources\Json\JsonResource;
-use Illuminate\Support\Collection;
+use Spatie\LaravelData\Optional;
 
 /**
- * @extends QueryRandomItemHandler<QueryRandomCharacterCommand, CharacterResource>
+ * @extends QueryRandomCharacterHandler<QueryRandomCharacterCommand, CharacterResource|CharacterCollection>
  */
-final class QueryRandomCharacterHandler extends QueryRandomItemHandler
+final class QueryRandomCharacterHandler implements RequestHandler
 {
-    public function __construct(CharacterRepository $repository)
+
+    /**
+     * @inheritDoc
+     */
+    public function handle($request): CharacterResource|CharacterCollection
     {
-        parent::__construct($repository);
+        $queryable = Character::query();
+
+        $limit = $request->limit instanceof Optional ? 1 : $request->limit;
+
+        $results = $queryable->random($limit);
+
+        return $results->count() === 1
+            ? new CharacterResource($results->first())
+            : new CharacterCollection($results, false);
     }
 
     /**
@@ -25,9 +38,4 @@ public function requestClass(): string
     {
         return QueryRandomCharacterCommand::class;
     }
-
-    protected function resource(Collection $results): JsonResource
-    {
-        return new CharacterResource($results->first());
-    }
 }

app/Features/QueryRandomMangaHandler.php

@@ -4,29 +4,32 @@
 
 use App\Contracts\RequestHandler;
 use App\Dto\QueryRandomMangaCommand;
+use App\Http\Resources\V4\MangaCollection;
 use App\Http\Resources\V4\MangaResource;
 use App\Manga;
 use Spatie\LaravelData\Optional;
 
 /**
- * @implements RequestHandler<QueryRandomMangaCommand, MangaResource>
+ * @implements RequestHandler<QueryRandomMangaCommand, MangaResource|MangaCollection>
  */
 final class QueryRandomMangaHandler implements RequestHandler
 {
     /**
      * @inheritDoc
      */
-    public function handle($request)
+    public function handle($request): MangaResource|MangaCollection
     {
         $queryable = Manga::query();
 
-        $o = Optional::create();
-        $sfwParam = $request->sfw === $o ? false : $request->sfw;
-        $unapprovedParam = $request->unapproved === $o ? false : $request->unapproved;
+        $sfwParam = $request->sfw instanceof Optional ? false : $request->sfw;
+        $unapprovedParam = $request->unapproved instanceof Optional ? false : $request->unapproved;
+        $limit = $request->limit instanceof Optional ? 1 : $request->limit;
 
-        return new MangaResource(
-            $queryable->random(1, $sfwParam, $unapprovedParam)->first()
-        );
+        $results = $queryable->random($limit, $sfwParam, $unapprovedParam);
+
+        return $results->count() === 1
+            ? new MangaResource($results->first())
+            : new MangaCollection($results, false);
     }
 
     /**

app/Features/QueryRandomPersonHandler.php

@@ -2,20 +2,33 @@
 
 namespace App\Features;
 
-use App\Contracts\PeopleRepository;
+use App\Contracts\RequestHandler;
 use App\Dto\QueryRandomPersonCommand;
+use App\Http\Resources\V4\PersonCollection;
 use App\Http\Resources\V4\PersonResource;
-use Illuminate\Http\Resources\Json\JsonResource;
-use Illuminate\Support\Collection;
+use App\Person;
+use Spatie\LaravelData\Optional;
 
 /**
- * @extends QueryRandomItemHandler<QueryRandomPersonCommand, PersonResource>
+ * @extends RequestHandler<QueryRandomPersonCommand, PersonResource|PersonCollection>
  */
-final class QueryRandomPersonHandler extends QueryRandomItemHandler
+final class QueryRandomPersonHandler implements RequestHandler
 {
-    public function __construct(PeopleRepository $repository)
+
+    /**
+     * @inheritDoc
+     */
+    public function handle($request): PersonResource|PersonCollection
     {
-        parent::__construct($repository);
+        $queryable = Person::query();
+
+        $limit = $request->limit instanceof Optional ? 1 : $request->limit;
+
+        $results = $queryable->random($limit);
+
+        return $results->count() === 1
+            ? new PersonResource($results->first())
+            : new PersonCollection($results, false);
     }
 
     /**
@@ -25,9 +38,4 @@ public function requestClass(): string
     {
         return QueryRandomPersonCommand::class;
     }
-
-    protected function resource(Collection $results): JsonResource
-    {
-        return new PersonResource($results->first());
-    }
 }