Merge pull request #2 from eufaturo/feature/responsable-and-query-builder-responses

Make responses Responsable and return SuccessResponse from QueryBuilder

Author: brunogaspar

.github/scripts/setup-php.sh

@@ -5,14 +5,10 @@ sudo add-apt-repository ppa:ondrej/php
 sudo apt-get update
 sudo apt-get install -y \
     php${PHP_VERSION} \
-    php${PHP_VERSION}-curl \
-    php${PHP_VERSION}-cgi \
     php${PHP_VERSION}-cli \
     php${PHP_VERSION}-curl \
-    php${PHP_VERSION}-dev \
-    php${PHP_VERSION}-fpm \
     php${PHP_VERSION}-intl \
     php${PHP_VERSION}-mbstring \
-    php${PHP_VERSION}-mysql \
+    php${PHP_VERSION}-sqlite3 \
     php${PHP_VERSION}-xml \
     php${PHP_VERSION}-zip

.github/workflows/tests.yml

@@ -27,16 +27,6 @@ jobs:
 
     runs-on: ubuntu-latest
 
-    services:
-      mysql:
-        image: mysql:8
-        env:
-          MYSQL_ALLOW_EMPTY_PASSWORD: yes
-          MYSQL_DATABASE: eufaturo_testing
-        ports:
-          - 3306:3306
-        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3
-
     steps:
       - name: Checkout Code
         uses: actions/checkout@v6

README.md

@@ -32,13 +32,11 @@ Use it in a controller:
 ```php
 final class ListController
 {
-    public function __invoke(Request $request, Response $response): JsonResponse
+    public function __invoke(Request $request)
     {
-        $products = QueryBuilder::for(Product::class, $request)
+        return QueryBuilder::for(Product::class, $request)
             ->fromResource(ProductResource::class)
             ->paginate();
-
-        return $response->success($products, ProductResource::class)->respond();
     }
 }
 ```

docs/introduction.mdx

@@ -62,18 +62,16 @@ final class ProductResource extends Resource
 }
 ```
 
-Use the QueryBuilder and Response in your controller:
+Use the QueryBuilder in your controller:
 
 ```php
 final class ListController
 {
-    public function __invoke(Request $request, Response $response): JsonResponse
+    public function __invoke(Request $request)
     {
-        $products = QueryBuilder::for(Product::class, $request)
+        return QueryBuilder::for(Product::class, $request)
             ->fromResource(ProductResource::class)
             ->paginate();
-
-        return $response->success($products, ProductResource::class)->respond();
     }
 }
 ```

docs/query-builder/overview.mdx

@@ -3,7 +3,7 @@ title: Overview
 description: Fluent query builder that ties everything together
 ---
 
-The `QueryBuilder` is a fluent wrapper that applies filtering, sorting, includes, and pagination from the request. It reads defaults from your [Resource](/resources/overview) and allowing overrides.
+The `QueryBuilder` is a fluent wrapper that applies filtering, sorting, includes, and pagination from the request. It reads defaults from your [Resource](/resources/overview) and allows overrides.
 
 ## Why use it?
 
@@ -18,13 +18,14 @@ $query = Product::query();
 (new IncludeParser(allowed: [...]))->apply($request, $query);
 
 $results = (new OffsetPaginator())->paginate($request, $query);
+
+return $response->success($results, ProductResource::class)->respond();
 ```
 
 With the QueryBuilder:
 
 ```php
-// With QueryBuilder
-$results = QueryBuilder::for(Product::class, $request)
+return QueryBuilder::for(Product::class, $request)
     ->fromResource(ProductResource::class)
     ->paginate();
 ```
@@ -34,23 +35,23 @@ $results = QueryBuilder::for(Product::class, $request)
 ```php
 use Eufaturo\ApiToolkit\QueryBuilder;
 
-$products = QueryBuilder::for(Product::class, $request)
+return QueryBuilder::for(Product::class, $request)
     ->fromResource(ProductResource::class)
     ->paginate();
-
-return $response->success($products, ProductResource::class)->respond();
 ```
 
 The QueryBuilder reads `allowedFilters()`, `allowedSorts()`, `defaultSort()`, and `allowedIncludes()` from the Resource and applies them automatically.
 
+The terminal methods (`paginate()`, `cursorPaginate()`, `get()`) return a `SuccessResponse` that implements Laravel's `Responsable` interface. You can return it directly from controllers without calling `->respond()`.
+
 ## Starting from an existing query
 
 You can pass an existing `Builder` instance instead of a model class:
 
 ```php
 $query = Product::query()->where('company_id', $companyId);
 
-$products = QueryBuilder::for($query, $request)
+return QueryBuilder::for($query, $request)
     ->fromResource(ProductResource::class)
     ->paginate();
 ```
@@ -59,21 +60,31 @@ $products = QueryBuilder::for($query, $request)
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `paginate()` | `LengthAwarePaginator` | Offset-based pagination |
-| `cursorPaginate()` | `CursorPaginator` | Cursor-based pagination |
-| `get()` | `Collection` | All results (no pagination) |
+| `paginate()` | `SuccessResponse` | Offset-based pagination |
+| `cursorPaginate()` | `SuccessResponse` | Cursor-based pagination |
+| `get()` | `SuccessResponse` | All results (no pagination) |
+
+All terminal methods return a `SuccessResponse` which is `Responsable`. You can chain `->meta()` or `->links()` before returning:
+
+```php
+return QueryBuilder::for(Product::class, $request)
+    ->fromResource(ProductResource::class)
+    ->paginate()
+    ->meta(['request_id' => $requestId]);
+```
 
 ## Accessing the underlying query
 
-Use `getQuery()` to access the Eloquent `Builder` before executing:
+Use `apply()` + `getQuery()` when you need direct access to the Eloquent Builder:
 
 ```php
 $builder = QueryBuilder::for(Product::class, $request)
-    ->fromResource(ProductResource::class);
+    ->fromResource(ProductResource::class)
+    ->apply();
 
 $query = $builder->getQuery();
-// Add custom logic
 $query->whereHas('inventory', fn ($q) => $q->where('quantity', '>', 0));
 
-$products = $builder->paginate();
+// Use Response class directly when working with raw queries
+return $response->success($query->paginate(20), ProductResource::class);
 ```

docs/quickstart.mdx

@@ -65,20 +65,16 @@ final class ProductResource extends Resource
 ```php app/Http/Controllers/Products/ListController.php
 use App\Http\Resources\ProductResource;
 use App\Models\Product;
-use Eufaturo\ApiToolkit\Http\Response;
 use Eufaturo\ApiToolkit\QueryBuilder;
-use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 
 final class ListController
 {
-    public function __invoke(Request $request, Response $response): JsonResponse
+    public function __invoke(Request $request)
     {
-        $products = QueryBuilder::for(Product::class, $request)
+        return QueryBuilder::for(Product::class, $request)
             ->fromResource(ProductResource::class)
             ->paginate();
-
-        return $response->success($products, ProductResource::class)->respond();
     }
 }
 ```
@@ -89,13 +85,12 @@ final class ListController
 use App\Http\Resources\ProductResource;
 use App\Models\Product;
 use Eufaturo\ApiToolkit\Http\Response;
-use Illuminate\Http\JsonResponse;
 
 final class ViewController
 {
-    public function __invoke(Product $product, Response $response): JsonResponse
+    public function __invoke(Product $product, Response $response)
     {
-        return $response->success($product, ProductResource::class)->respond();
+        return $response->success($product, ProductResource::class);
     }
 }
 ```

docs/resources/collections.mdx

@@ -14,7 +14,7 @@ When you pass an array, `Collection`, or paginator to a success response, the to
 ```php
 $products = Product::query()->paginate(20);
 
-return $response->success($products, ProductResource::class)->respond();
+return $response->success($products, ProductResource::class);
 ```
 
 ## Supported data types

docs/resources/links-and-meta.mdx

@@ -101,8 +101,7 @@ In addition to resource-level links and meta, you can add response-level meta an
 return $response
     ->success($products, ProductResource::class)
     ->meta(['request_id' => $requestId])
-    ->links(['documentation' => 'https://docs.example.com/products'])
-    ->respond();
+    ->links(['documentation' => 'https://docs.example.com/products']);
 ```
 
 These are added to the top-level JSON:API document, separate from the individual resource objects.

docs/responses/error-responses.mdx

@@ -3,10 +3,12 @@ title: Error Responses
 description: Build JSON:API error responses
 ---
 
+`ErrorResponse` implements Laravel's `Responsable` interface. The HTTP status code is derived from the status you pass to `error()`, so you can return it directly without calling `->respond()`.
+
 ## Basic error
 
 ```php
-return $this->response->error('Not Found', 'Product does not exist', 404)->respond();
+return $this->response->error('Not Found', 'Product does not exist', 404);
 ```
 
 ```json
@@ -26,8 +28,7 @@ return $this->response->error('Not Found', 'Product does not exist', 404)->respo
 ```php
 return $this->response
     ->error('Validation Error', 'Name is required', 422)
-    ->code('validation_error')
-    ->respond();
+    ->code('validation_error');
 ```
 
 ```json
@@ -51,22 +52,20 @@ Point to the field that caused the error:
 return $this->response
     ->error('Validation Error', 'Name is required', 422)
     ->code('validation_error')
-    ->source(['pointer' => '/data/attributes/name'])
-    ->respond();
+    ->source(['pointer' => '/data/attributes/name']);
 ```
 
 ## With meta
 
 ```php
 return $this->response
     ->error('Rate Limited', 'Too many requests', 429)
-    ->meta(['retry_after' => 60])
-    ->respond();
+    ->meta(['retry_after' => 60]);
 ```
 
-## Custom status code on respond
+## Custom headers
 
-Override the status code at response time:
+Use `->respond()` when you need custom headers:
 
 ```php
 return $this->response

docs/responses/overview.mdx

@@ -20,6 +20,24 @@ final class ProductController
 }
 ```
 
+## Responsable
+
+Both `SuccessResponse` and `ErrorResponse` implement Laravel's `Responsable` interface. You can return them directly from controllers without calling `->respond()`:
+
+```php
+// No ->respond() needed
+return $this->response->success($product, ProductResource::class);
+
+// Also works with errors
+return $this->response->error('Not Found', 'Product does not exist', 404);
+```
+
+Use `->respond()` when you need a custom status code or headers:
+
+```php
+return $this->response->success($product, ProductResource::class)->respond(201);
+```
+
 ## Inject via constructor
 
 The `Response` class is registered as a singleton in the service container. Inject it via constructor dependency injection: