PHPackages                             pjadanowski/scramble-extras - 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. pjadanowski/scramble-extras

ActiveLibrary[API Development](/categories/api)

pjadanowski/scramble-extras
===========================

Spatie Laravel Data + Query Builder integration for dedoc/scramble. A free, open replacement for scramble-pro covering output/input Data schemas, all Spatie validation attributes, query-builder filters/sorts/includes, jsonPaginate, and persistent schema caching.

v0.3.0(1mo ago)0142MITPHPPHP ^8.2CI passing

Since May 4Pushed 1mo agoCompare

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

READMEChangelog (1)Dependencies (18)Versions (4)Used By (0)

scramble-extras
===============

[](#scramble-extras)

[![tests](https://github.com/pjadanowski/scramble-extras/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/pjadanowski/scramble-extras/actions/workflows/tests.yml)

A free, open Laravel package that adds full **Spatie ecosystem** support to [dedoc/scramble](https://github.com/dedoc/scramble) — covering everything `scramble-pro` does for the integrations most projects actually need.

Features
--------

[](#features)

- **Spatie Laravel Data** — output and input (request body) schemas auto-generated from your `Data` classes. Honors `MapName`/`MapInputName`, `Optional`, `Lazy`, `#[Computed]`, `#[Hidden]`, `#[DataCollectionOf]`, and reads `@example`/`@default` from property phpdoc.
- **All ~80 Spatie validation attributes → OpenAPI fields** — `#[Email]` → `format: email`, `#[Min(3)]` → `minLength`, `#[GreaterThan(0)]` → `exclusiveMinimum`, `#[In(...)]` / `#[Enum(SomeEnum::class)]` → `enum`, `#[Regex]` → `pattern`, `#[Image]` → `contentMediaType: image/*`, plus description notes for `#[Same]`, `#[Confirmed]`, `#[Exists]`, `#[RequiredIf]`, etc.
- **`PaginatedDataCollection`, `CursorPaginatedDataCollection`, `DataCollection`** — proper response envelopes (Laravel paginator format / cursor format / plain array).
- **Spatie Laravel Query Builder** — `allowedFilters` / `allowedSorts` / `allowedIncludes` / `allowedFields` / `defaultSort` / `jsonPaginate()` parsed via AST. `AllowedFilter::exact($column)` on an enum-cast Eloquent column emits `enum: [...]` automatically.
- **Persistent schema cache** — file-based, mtime-invalidated. `php artisan scramble-extras:cache:clear` to wipe.

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

[](#requirements)

- PHP 8.2+
- Laravel 11, 12, or 13
- `dedoc/scramble` ^0.12.20

Install
-------

[](#install)

```
composer require pjadanowski/scramble-extras
```

The service provider auto-registers all extensions via Laravel's package discovery — no config touching needed. Install [`dedoc/scramble`](https://github.com/dedoc/scramble) itself if you haven't already, and you're done: your `Data` classes start showing up in the generated docs.

To document `allowedFilters/Sorts/Includes/Fields` you also need `spatie/laravel-query-builder` (the query-builder extension self-registers only when that package is present):

```
composer require spatie/laravel-query-builder
```

Configuration
-------------

[](#configuration)

There's nothing to configure to get started. If you want to tune the cache, publish the config:

```
php artisan vendor:publish --tag=scramble-extras-config
```

```
// config/scramble-extras.php
return [
    'cache' => [
        'enabled' => env('SCRAMBLE_EXTRAS_CACHE', true),
        'path' => env('SCRAMBLE_EXTRAS_CACHE_PATH'), // null = storage/framework/cache/scramble-extras/schemas.php
    ],
];
```

Or just set the env vars — e.g. disable the cache while iterating on `Data` classes locally:

```
SCRAMBLE_EXTRAS_CACHE=false
```

How it plugs in
---------------

[](#how-it-plugs-in)

The package boots in two ways:

1. Calls `Scramble::registerExtensions(...)` in its service provider, contributing TypeToSchema, OperationExtension, and InferExtension classes that Scramble picks up automatically.
2. Calls `Scramble::configure()->withParametersExtractors(...)` to prepend a Data-aware parameter extractor for request bodies typed with `Data` subclasses.

You don't have to add anything to `config/scramble.php`.

Cache
-----

[](#cache)

The package transparently caches built schemas in `storage/framework/cache/scramble-extras/schemas.php`. Cache invalidates per-class on `filemtime()` change, so editing a `Data` class auto-rebuilds just that class on the next export. The cache file also carries a signature derived from the installed Scramble version, so it self-invalidates after a `dedoc/scramble` upgrade — no manual clear required.

Writes are deferred: a full export builds every schema in memory and persists the cache **once** on shutdown, rather than rewriting the file per class.

To wipe manually:

```
php artisan scramble-extras:cache:clear
```

Request bodies vs responses
---------------------------

[](#request-bodies-vs-responses)

A `Data` class is often used as both a response and a request body, and the two projections differ — `#[Computed]` is output-only, `#[Hidden]` is input-only, and `Optional` / `#[MapInputName]` change required-ness and field names. To keep both faithful, **request body schemas are inlined** (rendered directly on the operation) instead of `$ref`-ing the shared output component. Response schemas remain reusable `$ref` components.

What's NOT covered (yet)
------------------------

[](#whats-not-covered-yet)

Long-tail features still on the roadmap:

- `multipart/form-data` request bodies for `Data` classes containing `UploadedFile` properties
- Sparse fieldsets rendered as proper enum array params (currently emitted as `string` with allowed values in the description)
- Polymorphic `Data` with discriminator schemas

Testing
-------

[](#testing)

```
composer install
composer test
```

The suite covers the attribute → OpenAPI translation, the query-builder AST extraction, the schema cache, the return-type inference, and a full end-to-end Scramble generation pass (request bodies, response `$ref`s, paginated envelopes, and query parameters) booted with `orchestra/testbench`.

License
-------

[](#license)

MIT

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance91

Actively maintained with recent releases

Popularity15

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

Every ~19 days

Total

3

Last Release

42d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/16418436?v=4)[Paweł Jadanowski](/maintainers/pjadanowski)[@pjadanowski](https://github.com/pjadanowski)

---

Top Contributors

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

---

Tags

spatielaraveldocumentationopenapilaravel-query-builderlaravel-datascramble

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/pjadanowski-scramble-extras/health.svg)

```
[![Health](https://phpackages.com/badges/pjadanowski-scramble-extras/health.svg)](https://phpackages.com/packages/pjadanowski-scramble-extras)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M347](/packages/psalm-plugin-laravel)[spatie/laravel-medialibrary

Associate files with Eloquent models

6.2k43.2M656](/packages/spatie-laravel-medialibrary)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M246](/packages/laravel-ai)[spatie/laravel-health

Monitor the health of a Laravel application

87912.0M177](/packages/spatie-laravel-health)[laravel/surveyor

Static analysis tool for Laravel applications.

86121.4k14](/packages/laravel-surveyor)[api-platform/laravel

API Platform support for Laravel

58174.6k17](/packages/api-platform-laravel)

PHPackages © 2026

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