✨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

@@ -13,5 +13,6 @@
  */
 final class QueryRandomAnimeCommand extends Data implements DataRequest
 {
-    use HasSfwParameter, HasUnapprovedParameter;
+    use HasSfwParameter,
+        HasUnapprovedParameter;
 }

app/Dto/QueryRandomAnimeListCommand.php

@@ -0,0 +1,20 @@
+<?php
+
+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 Spatie\LaravelData\Data;
+
+/**
+ * @implements DataRequest<AnimeCollection>
+ */
+final class QueryRandomAnimeListCommand extends Data implements DataRequest
+{
+    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;
 

app/Dto/QueryRandomCharacterListCommand.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Dto;
+
+use App\Contracts\DataRequest;
+use App\Dto\Concerns\HasLimitParameterWithSmallerMax;
+use App\Http\Resources\V4\CharacterCollection;
+use Spatie\LaravelData\Data;
+
+/**
+ * @implements DataRequest<CharacterCollection>
+ */
+final class QueryRandomCharacterListCommand extends Data implements DataRequest
+{
+    use HasLimitParameterWithSmallerMax;
+}

app/Dto/QueryRandomMangaCommand.php

@@ -13,5 +13,6 @@
  */
 final class QueryRandomMangaCommand extends Data implements DataRequest
 {
-    use HasSfwParameter, HasUnapprovedParameter;
+    use HasSfwParameter,
+        HasUnapprovedParameter;
 }

app/Dto/QueryRandomMangaListCommand.php

@@ -0,0 +1,20 @@
+<?php
+
+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 Spatie\LaravelData\Data;
+
+/**
+ * @implements DataRequest<MangaCollection>
+ */
+final class QueryRandomMangaListCommand extends Data implements DataRequest
+{
+    use HasSfwParameter,
+        HasUnapprovedParameter,
+        HasLimitParameterWithSmallerMax;
+}

app/Dto/QueryRandomPersonListCommand.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Dto;
+
+use App\Contracts\DataRequest;
+use App\Dto\Concerns\HasLimitParameterWithSmallerMax;
+use App\Http\Resources\V4\PersonCollection;
+use Spatie\LaravelData\Data;
+
+/**
+ * @implements DataRequest<PersonCollection>
+ */
+final class QueryRandomPersonListCommand 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;
 

app/Dto/QueryRandomUserListCommand.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Dto;
+
+use App\Contracts\DataRequest;
+use App\Dto\Concerns\HasLimitParameterWithSmallerMax;
+use App\Http\Resources\V4\UserCollection;
+use Spatie\LaravelData\Data;
+
+/**
+ * @implements DataRequest<UserCollection>
+ */
+final class QueryRandomUserListCommand 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/QueryAnimeSchedulesHandler.php

@@ -8,6 +8,7 @@
 use App\Http\Resources\V4\AnimeCollection;
 use App\Support\CachedData;
 use Illuminate\Support\Env;
+use Spatie\LaravelData\Optional;
 
 /**
  * @implements RequestHandler<QueryAnimeSchedulesCommand, AnimeCollection>
@@ -24,7 +25,7 @@ public function __construct(private readonly AnimeRepository $repository)
     public function handle($request)
     {
         $requestParams = collect($request->all());
-        $limit = $requestParams->get("limit");
+        $limit = $request->limit instanceof Optional ? max_results_per_page() : $request->limit;
         $results = $this->repository->getCurrentlyAiring($request->filter);
         // apply sfw, kids and unapproved filters
         /** @noinspection PhpUndefinedMethodInspection */

app/Features/QueryAnimeSeasonHandlerBase.php

@@ -12,6 +12,7 @@
 use Illuminate\Contracts\Database\Query\Builder;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Carbon;
+use Spatie\LaravelData\Optional;
 use Symfony\Component\HttpFoundation\Exception\BadRequestException;
 
 /**
@@ -32,11 +33,12 @@ public function handle($request): JsonResponse
     {
         $requestParams = collect($request->all());
         $type = $requestParams->has("filter") ? $request->filter : null;
+        $limit = $request->limit instanceof Optional ? max_results_per_page() : $request->limit;
         $results = $this->getSeasonItems($request, $type);
         // apply sfw, kids and unapproved filters
         /** @noinspection PhpUndefinedMethodInspection */
         $results = $results->filter($requestParams);
-        $results = $results->paginate($request->limit, ["*"], null, $request->page);
+        $results = $results->paginate($limit, ["*"], null, $request->page);
 
         $animeCollection = new AnimeCollection($results);
         $response = $animeCollection->response();

app/Features/QueryRandomAnimeHandler.php

@@ -20,13 +20,12 @@
     {
         $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;
 
-        return new AnimeResource(
-            $queryable->random(1, $sfwParam, $unapprovedParam)->first()
-        );
+        $results = $queryable->random(1, $sfwParam, $unapprovedParam);
+
+        return new AnimeResource($results->first());
     }
 
     /**

app/Features/QueryRandomAnimeListHandler.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Features;
+
+use App\Anime;
+use App\Contracts\RequestHandler;
+use App\Dto\QueryRandomAnimeCommand;
+use App\Dto\QueryRandomAnimeListCommand;
+use App\Http\Resources\V4\AnimeCollection;
+use Spatie\LaravelData\Optional;
+
+/**
+ * @implements RequestHandler<QueryRandomAnimeCommand, AnimeCollection>
+ */
+final class QueryRandomAnimeListHandler implements RequestHandler
+{
+    /**
+     * @inheritDoc
+     */
+    public function handle($request): AnimeCollection
+    {
+        $queryable = Anime::query();
+
+        $sfwParam = $request->sfw instanceof Optional ? false : $request->sfw;
+        $unapprovedParam = $request->unapproved instanceof Optional ? false : $request->unapproved;
+        $limit = $request->limit instanceof Optional ? 1 : $request->limit;
+
+        $results = $queryable->random($limit, $sfwParam, $unapprovedParam);
+
+        return new AnimeCollection($results, false);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function requestClass(): string
+    {
+        return QueryRandomAnimeListCommand::class;
+    }
+}

app/Features/QueryRandomCharacterHandler.php

@@ -2,20 +2,27 @@
 
 namespace App\Features;
 
-use App\Contracts\CharacterRepository;
+use App\Character;
+use App\Contracts\RequestHandler;
 use App\Dto\QueryRandomCharacterCommand;
 use App\Http\Resources\V4\CharacterResource;
-use Illuminate\Http\Resources\Json\JsonResource;
-use Illuminate\Support\Collection;
 
 /**
- * @extends QueryRandomItemHandler<QueryRandomCharacterCommand, CharacterResource>
+ * @extends QueryRandomCharacterHandler<QueryRandomCharacterCommand, CharacterResource>
  */
-final class QueryRandomCharacterHandler extends QueryRandomItemHandler
+final class QueryRandomCharacterHandler implements RequestHandler
 {
-    public function __construct(CharacterRepository $repository)
+
+    /**
+     * @inheritDoc
+     */
+    public function handle($request): CharacterResource
     {
-        parent::__construct($repository);
+        return new CharacterResource(
+            Character::query()
+                ->random(1)
+                ->first()
+        );
     }
 
     /**
@@ -25,9 +32,4 @@
     {
         return QueryRandomCharacterCommand::class;
     }
-
-    protected function resource(Collection $results): JsonResource
-    {
-        return new CharacterResource($results->first());
-    }
 }

app/Features/QueryRandomCharacterListHandler.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Features;
+
+use App\Character;
+use App\Contracts\RequestHandler;
+use App\Dto\QueryRandomCharacterListCommand;
+use App\Http\Resources\V4\CharacterCollection;
+use Spatie\LaravelData\Optional;
+
+/**
+ * @implements RequestHandler<QueryRandomCharacterListCommand, CharacterCollection>
+ */
+final class QueryRandomCharacterListHandler implements RequestHandler
+{
+    /**
+     * @inheritDoc
+     */
+    public function handle($request): CharacterCollection
+    {
+        $queryable = Character::query();
+        $limit = $request->limit instanceof Optional ? 1 : $request->limit;
+        $results = $queryable->random($limit);
+
+        return new CharacterCollection($results, false);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function requestClass(): string
+    {
+        return QueryRandomCharacterListCommand::class;
+    }
+}