Add QueryBuilder for models

Author: KroderDev

CHANGELOG.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+### Added
+- Query builder with `where()->get()` support for remote models.
 
 ## [0.4.1] - 2025-07-10
 ### Added

src/Models/Model.php

@@ -39,6 +39,22 @@ protected static function client(): ApiGatewayClientInterface
         return app(ApiGatewayClientInterface::class);
     }
 
+    /**
+     * Start a new query for the model.
+     */
+    public static function query(): QueryBuilder
+    {
+        return new QueryBuilder(static::class);
+    }
+
+    /**
+     * Filter models by the given column and value.
+     */
+    public static function where(string $column, mixed $value): QueryBuilder
+    {
+        return static::query()->where($column, $value);
+    }
+
     /**
      * Get all models.
      */

src/Models/QueryBuilder.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Kroderdev\LaravelMicroserviceCore\Models;
+
+use Illuminate\Support\Collection;
+
+class QueryBuilder
+{
+    protected string $model;
+
+    protected array $filters = [];
+
+    public function __construct(string $model)
+    {
+        $this->model = $model;
+    }
+
+    public function where(string $column, mixed $value): static
+    {
+        $this->filters[$column] = $value;
+
+        return $this;
+    }
+
+    public function get($columns = ['*']): Collection
+    {
+        $model = $this->model;
+
+        $response = $model::client()->get($model::endpoint(), $this->filters);
+        $data = $this->parseResponse($response);
+
+        return $model::fromCollection($data['data'] ?? $data);
+    }
+
+    protected function parseResponse($response): array
+    {
+        if ($response === null) {
+            return [];
+        }
+
+        if (is_array($response)) {
+            return $response;
+        }
+
+        if ($response instanceof Collection) {
+            return $response->toArray();
+        }
+
+        if (method_exists($response, 'json')) {
+            return $response->json();
+        }
+
+        return (array) $response;
+    }
+}

tests/Models/ApiModelTest.php

@@ -209,6 +209,29 @@ public function delete_users_gateway()
         ], $this->gateway->getCalls());
     }
 
+    /** @test */
+    public function where_get_filters_results()
+    {
+        $this->gateway = new class () extends FakeGatewayClient {
+            public function get(string $uri, array $query = [])
+            {
+                parent::get($uri, $query);
+
+                return ['data' => [
+                    ['id' => 7, 'name' => $query['name'] ?? ''],
+                ]];
+            }
+        };
+        $this->app->bind(ApiGatewayClientInterface::class, fn () => $this->gateway);
+
+        $users = RemoteUser::where('name', 'Alice')->get();
+
+        $this->assertSame([
+            ['method' => 'GET', 'uri' => '/users', 'query' => ['name' => 'Alice']],
+        ], $this->gateway->getCalls());
+        $this->assertCount(1, $users);
+        $this->assertEquals('Alice', $users[0]->name);
+    }
 
     /** @test */
     public function from_api_response_maps_nested_relations()