README

Introduction

This is the Scramble extension, which detects the usage of the Spatie query builder in your api routes and automatically adds applicable query parameters to the openapi definition.

Installation

After you publish the package on Packagist:

composer require zaruto/scramble-spatie-query-builder

Until the package is published, install it directly from your GitHub repository:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/zaruto/scramble-spatie-query-builder.git"
        }
    ],
    "require": {
        "zaruto/scramble-spatie-query-builder": "dev-main"
    }
}

Then run:

composer update zaruto/scramble-spatie-query-builder

Supported baseline:

• PHP ^8.3
• dedoc/scramble ^0.13.16
• spatie/laravel-query-builder ^7.0.1
• Laravel 12 test/dev stack

Usage

1. Register the extension in your config/scramble.php file.

'extensions' => [
    // ...
    \Zaruto\ScrambleSpatieQueryBuilder\AllowedFieldsExtension::class,
    \Zaruto\ScrambleSpatieQueryBuilder\AllowedSortsExtension::class,
    \Zaruto\ScrambleSpatieQueryBuilder\AllowedFiltersExtension::class,
    \Zaruto\ScrambleSpatieQueryBuilder\AllowedIncludesExtension::class,
//    \Zaruto\ScrambleSpatieQueryBuilder\AllowedFilterModesExtension::class
],

1. Use Spatie Query Builder in your controller or route action as usual.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

class UserController extends Controller
{
    public function index(): AnonymousResourceCollection
    {
        $users = QueryBuilder::for(User::query())
            ->allowedFields(['id', 'name', 'email'])
            ->allowedFilters([
                'name',
                AllowedFilter::exact('email'),
            ])
            ->allowedIncludes(['posts', 'roles'])
            ->allowedSorts(['name', 'created_at'])
            ->paginate();

        return UserResource::collection($users);
    }
}

1. Open your Scramble docs. For routes that use Spatie Query Builder, the extension will add query parameters such as:

• fields
• filter
• include
• sort
• filter_mode when AllowedFilterModesExtension is enabled

1. Example query string:

/api/users?fields[users]=id,name,email&filter[name]=john&include=posts&sort=-created_at

Customization

By default this extension automatically updates openapi definition for you, but if you want to customize its default behaviour, you can do it in the following way

1. Open your AppServiceProvider.php and add the following code example in the boot method

public function boot(): void
{
    // ...
    AllowedIncludesExtension::hook(function(Operation $operation, Parameter $parameter) {
        // Customize the example
        $parameter->example(['repositories.issues', 'repositories']);
        // Customize the description
        $parameter->description('Allows you to include additional model relations in the response');
    });
}

1. Customize for your needs

Publishing

To publish this as your own package:

1. Create a public GitHub repository named scramble-spatie-query-builder under your zaruto account.
2. Push this code to https://github.com/zaruto/scramble-spatie-query-builder.
3. Sign in to Packagist with your GitHub account.
4. Submit the repository URL to Packagist.
5. After Packagist indexes the repository, install it with composer require zaruto/scramble-spatie-query-builder.
6. Add the Packagist service hook in GitHub so new tags and releases are picked up automatically.