PHPackages                             lokiwich/scramble-spatie-query-builder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. lokiwich/scramble-spatie-query-builder

ActiveLibrary[API Development](/categories/api)

lokiwich/scramble-spatie-query-builder
======================================

ScrambleSpatieQueryBuilder — automatically document Spatie Query Builder in Dedoc Scramble OpenAPI docs.

v0.1.0(2w ago)113↓25%MITPHPPHP ^8.3

Since May 24Pushed 2w agoCompare

[ Source](https://github.com/lokiwich/scramble-spatie-query-builder)[ Packagist](https://packagist.org/packages/lokiwich/scramble-spatie-query-builder)[ RSS](/packages/lokiwich-scramble-spatie-query-builder/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (7)Versions (2)Used By (0)

ScrambleSpatieQueryBuilder
==========================

[](#scramblespatiequerybuilder)

[![Latest Version on Packagist](https://camo.githubusercontent.com/29ed31f77beae8e770a5677d7380f7908970e65a05aeb43316f17fb81261ff6e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c6f6b69776963682f736372616d626c652d7370617469652d71756572792d6275696c6465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lokiwich/scramble-spatie-query-builder)[![Total Downloads](https://camo.githubusercontent.com/77b7694bf50af4a33b19188f51e6ccd38a31e9f6e3074e5ae05ea61f3dcec92a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c6f6b69776963682f736372616d626c652d7370617469652d71756572792d6275696c6465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lokiwich/scramble-spatie-query-builder)

Automatically document [Spatie Laravel Query Builder](https://github.com/spatie/laravel-query-builder) filters, sorts, includes, and fields in [Dedoc Scramble](https://github.com/dedoc/scramble) OpenAPI docs.

No PHPDoc annotations required — the package inspects your controller code and registers Scramble extensions automatically.

Requirements
------------

[](#requirements)

- PHP 8.3+
- Laravel 12 or 13
- `dedoc/scramble` ^0.13
- `spatie/laravel-query-builder` ^7.0

Installation
------------

[](#installation)

```
composer require lokiwich/scramble-spatie-query-builder
```

The service provider auto-registers four Scramble operation transformers. You do **not** need to add anything to `config/scramble.php`.

Usage
-----

[](#usage)

Use Spatie Query Builder in your controllers as usual:

```
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

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

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

Scramble will document query parameters using names from `config/query-builder.php` (`filter`, `sort`, `include`, `fields`). When `scramble.flatten_deep_query_parameters` is `true` (default), filters and fields use bracket notation (`filter[name]`, `fields[users]`).

Filter parameters are documented only when you call `allowedFilters()` explicitly, matching [Spatie's filtering rules](https://spatie.be/docs/laravel-query-builder/v7/features/filtering). Supported definitions include variadic strings, arrays, `AllowedFilter::partial` / `exact` / `beginsWith` / `endsWith` / `operator` / `scope` / `belongsTo` / `callback` / `custom` / `trashed`, filter aliases, `groupOr` / `groupAnd`, and chained `ignore()`, `nullable()`, and `default()`.

Customization
-------------

[](#customization)

Hook into any extension before parameters are added:

```
use Lokiwich\ScrambleSpatieQueryBuilder\Extensions\DocumentsAllowedIncludes;
use Dedoc\Scramble\Support\Generator\Operation;
use Dedoc\Scramble\Support\Generator\Parameter;

DocumentsAllowedIncludes::hook(function (Operation $operation, Parameter $parameter) {
    $parameter->description('Eager-load related resources');
});
```

Return `true` from the hook to prevent the parameter from being added.

Testing
-------

[](#testing)

```
composer install
composer test
```

Tests use [Orchestra Testbench](https://github.com/orchestra/testbench) and Scramble's `Generator` directly — no host application required.

License
-------

[](#license)

MIT © [lokiwich](https://github.com/lokiwich)

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance97

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

16d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/696fcd1394fafbaa0eaec46b50f0ad37af81a094727c0a68e5939cfe19a610a7?d=identicon)[lokiwich](/maintainers/lokiwich)

---

Top Contributors

[![lokiwich](https://avatars.githubusercontent.com/u/35873574?v=4)](https://github.com/lokiwich "lokiwich (4 commits)")

---

Tags

spatielaravelswaggeropenapiquery builderscrambleScrambleSpatieQueryBuilder

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/lokiwich-scramble-spatie-query-builder/health.svg)

```
[![Health](https://phpackages.com/badges/lokiwich-scramble-spatie-query-builder/health.svg)](https://phpackages.com/packages/lokiwich-scramble-spatie-query-builder)
```

###  Alternatives

[kirschbaum-development/laravel-openapi-validator

Automatic OpenAPI validation for Laravel HTTP tests

581.2M5](/packages/kirschbaum-development-laravel-openapi-validator)[api-platform/laravel

API Platform support for Laravel

59156.3k10](/packages/api-platform-laravel)[exonn-gmbh/scramble-spatie-query-builder

This is the Scramble extension, which detects the usage of the Spatie query builder and adds applicable query parameters to the openapi definitions

124.3k](/packages/exonn-gmbh-scramble-spatie-query-builder)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)