use laravel-data for API requests and responses (#40)

* feat: use laravel-data for theme query requests

* test: add bruno test for all fields for 100-bytes

* refactor: replace ApiResultsResponse with specialized response class

app/Data/WpOrg/Author.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Data\WpOrg;
+
+use Spatie\LaravelData\Data;
+
+class Author extends Data
+{
+    public function __construct(
+        public readonly string $user_nicename,
+        public readonly string $profile,
+        public readonly string $avatar,
+        public readonly string $display_name,
+        public readonly string $author,
+        public readonly string $author_url,
+    ) {}
+}

app/Data/WpOrg/PageInfo.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace App\Data\WpOrg;
+
+use Spatie\LaravelData\Data;
+
+class PageInfo extends Data
+{
+    public function __construct(
+        public readonly int $page,
+        public readonly int $pages,
+        public readonly int $results,
+    ) {}
+}

app/Data/WpOrg/Themes/QueryThemesRequest.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace App\Data\WpOrg\Themes;
+
+use Illuminate\Http\Request;
+use Spatie\LaravelData\Data;
+
+class QueryThemesRequest extends Data
+{
+    public const ACTION = 'query_themes';
+
+    /**
+     * @param ?string $search
+     * @param ?string[] $tags
+     * @param ?string $theme
+     * @param ?string $author
+     * @param ?string $browse
+     * @param ?array<string,bool> $fields
+     * @param int $page
+     * @param int $per_page
+     */
+    public function __construct(
+        public readonly ?string $search = null, // text to search
+        public readonly ?array $tags = null,    // tag or set of tags
+        public readonly ?string $theme = null,  // slug of a specific theme
+        public readonly ?string $author = null, // wp.org username of author
+        public readonly ?string $browse = null, // one of popular|featured|updated|new
+        public readonly ?array $fields = null,
+        public readonly int $page = 1,
+        public readonly int $per_page = 24,
+    ) {}
+
+    public static function fromRequest(Request $request): self
+    {
+        $req = $request->query('request');
+        if (array_key_exists('tag', $req)) {
+            $req['tags'] = is_array($req['tag']) ? $req['tag'] : [$req['tag']];
+            unset($req['tag']);
+        }
+        return static::from($req);
+    }
+}
+
+// public const FIELDS_DEFAULT = [
+//     'description' => false,
+//     'sections' => false,
+//     'rating' => true,
+//     'ratings' => false,
+//     'downloaded' => true,
+//     'download_link' => true,
+//     'last_updated' => true,
+//     'homepage' => true,
+//     'tags' => true,
+//     'template' => true,
+//     'parent' => false,
+//     'versions' => false,
+//     'screenshot_url' => true,
+//     'active_installs' => false,
+// ];

app/Data/WpOrg/Themes/QueryThemesResponse.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Data\WpOrg\Themes;
+
+use App\Data\WpOrg\PageInfo;
+use Spatie\LaravelData\Attributes\MapOutputName;
+use Spatie\LaravelData\Data;
+use stdClass;
+
+class QueryThemesResponse extends Data
+{
+    /**
+     * @param PageInfo $pageInfo
+     * @param array<string,mixed> $themes   // TODO: use Collection<ThemeResponse>
+     */
+    public function __construct(
+        #[MapOutputName('info')]
+        public readonly PageInfo $pageInfo,
+        public readonly array $themes,
+    ) {}
+
+    /** for API version 1.0 responses only -- do not use this otherwise! */
+    public function toStdClass(): stdClass
+    {
+        return (object) ['info' => $this->pageInfo->toArray(), 'themes' => $this->themes];
+    }
+}

app/Data/WpOrg/Themes/ThemeInformationRequest.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Data\WpOrg\Themes;
+
+use Illuminate\Http\Request;
+use Spatie\LaravelData\Data;
+
+class ThemeInformationRequest extends Data
+{
+    public const ACTION = 'theme_information';
+
+    /**
+     * @param string $slug
+     * @param ?array<string,bool> $fields
+     */
+    public function __construct(
+        public readonly string $slug,
+        public readonly ?array $fields = null,
+    ) {}
+
+    public static function fromRequest(Request $request): self
+    {
+        return static::from($request->query('request'));
+    }
+}

app/Data/WpOrg/Themes/ThemeResponse.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace App\Data\WpOrg\Themes;
+
+use App\Data\WpOrg\Author;
+use Carbon\CarbonImmutable;
+use Spatie\LaravelData\Data;
+
+// WORK IN PROGRESS: not used yet.  many fields need to be made nullable or Optional.
+
+class ThemeResponse extends Data
+{
+    /**
+     * @param string $name
+     * @param string $slug
+     * @param string $version
+     * @param string $preview_url
+     * @param Author $author
+     * @param string $screenshot_url
+     * @param array{1:int, 2:int, 3:int, 4:int, 5:int} $ratings
+     * @param int $rating
+     * @param int $num_ratings
+     * @param string $reviews_url
+     * @param int $downloaded
+     * @param int $active_installs
+     * @param CarbonImmutable $last_updated
+     * @param CarbonImmutable $last_updated_time
+     * @param CarbonImmutable $creation_time
+     * @param string $homepage
+     * @param array<string,string> $sections
+     * @param string $download_link
+     * @param array<string,string> $tags
+     * @param array<string,string> $versions
+     * @param bool $requires
+     * @param string $requires_php
+     * @param bool $is_commercial
+     * @param string|bool $external_support_url
+     * @param bool $is_community
+     * @param string $external_repository_url
+     */
+    public function __construct(
+        public readonly string $name,
+        public readonly string $slug,
+        public readonly string $version,
+        public readonly string $preview_url,
+        public readonly Author $author,
+        public readonly string $screenshot_url,
+        public readonly array $ratings, // [1 => int, 2 => int, 3 => int, 4 => int, 5 => int]
+        public readonly int $rating,    // ??? between 0-100?
+        public readonly int $num_ratings,
+        public readonly string $reviews_url,
+        public readonly int $downloaded,
+        public readonly int $active_installs,
+        public readonly CarbonImmutable $last_updated,
+        public readonly CarbonImmutable $last_updated_time,
+        public readonly CarbonImmutable $creation_time,
+        public readonly string $homepage,
+        public readonly array $sections,
+        public readonly string $download_link,
+        public readonly array $tags,
+        public readonly array $versions,
+        public readonly bool $requires,
+        public readonly string $requires_php,
+        public readonly bool $is_commercial,
+        public readonly string|bool $external_support_url, // yep, actual wp.org data has it as false
+        public readonly bool $is_community,
+        public readonly string $external_repository_url,
+    ) {}
+}