Releases

What’s Changed

• Fixed document level tags ordering when using weight argument on #[Group] attribute by @romalytvynenko in #870
• Fix setOperationId called in an operation transformer not working by @romalytvynenko in #872

What’s Changed

• Fixed incorrect generic creation when looking for JSON resource in anonymous resource collection by @romalytvynenko in #862
• Fixed memory leak when running tests if there are extensions registered via programmatic API by @romalytvynenko in #864
• Allow using #[Group] attribute on route’s controller methods by @romalytvynenko in #865

What’s Changed

• Fixed bool typehint on authorize prevented Scramble into properly inferring 403 response absence by @romalytvynenko in #857
• Add support for inferring a type on property fetch or method call on an argument by @romalytvynenko in #858
• Fixed fully qualified names resolution of methods defined in traits by @romalytvynenko in #860

What’s Changed

• Added $attributes and $relationships properties support for timacdonald/json-api
• Add json-api toLinks support by @romalytvynenko in #56
• Added spatie/laravel-json-api-paginate support by @romalytvynenko in #57
• json-api improvements by @romalytvynenko in #58
• Bump dependabot/fetch-metadata from 2.2.0 to 2.4.0 by @dependabot in #59
• PHPstan with baseline by @romalytvynenko in #60

Paginated collections inference

Now, when returning API resource collections with paginators from the controllers, Scramble will automatically document the correct response. Previously you needed to manually annotate it. This is achieved by inferring the type of the paginators you get by calling a family of *paginate methods.

 /**
  * List available todo items.
- *
- * @response AnonymousResourceCollection<LengthAwarePaginator<TodoItemResource>>
  */
public function index()
{
    return TodoItemResource::collection(TodoItem::paginate());
}

This is particularly useful when you have some additional data together with the paginated collection. Previously it was tricky and not possible to have them both due to the annotation limitations.

public function index()
{
    $users = User::query()->paginate();

    return UserResource::collection($users)->additional([
        /** The total count of users */
        'count' => (int) $users->count(),
    ]);
}

Result:

<img width=“688” alt=“image” src=“https://github.com/user-attachments/assets/6a0ec1a2-e568-45f9-8842-1f9feddd1a7b” />

Authorization documentation improvements

Now Scramble recognizes possible 403 (authorization error) in more cases.

When you call Gate::authorize, Scramble will automatically document 403 response:

public function store(Request $request)
{
    Gate::authorize('create', User::class);

    $data = $request->validate([
        'name' => ['required', 'string'],
        'email' => ['required', 'email'],
    ]);

    return new UserResource(User::create($data));
}

Also now when you use the middleware created by Authorize::using, Scramble will also properly document the possible 403 response:

class CreateUserController extends Controller implements HasMiddleware
{
    public static function middleware(): array
    {
        return [
            Authorize::using('create', User::class)
        ];
    }

    public function store(Request $request)
    {
        $data = $request->validate([
            'name' => ['required', 'string'],
            'email' => ['required', 'email'],
        ]);

        return new UserResource(User::create($data));
    }
}

Thanks to @olivernybroe and @chrisvanlier2005 for these improvements.

What’s Changed

• Add sometimes validation rule support by @SocolaDaiCa in #802
• Fix authorization when using Authorize middleware by @olivernybroe in #820
• Make logo optional to prevent broken image by @vinkla in #821
• Extend inference API: added the ability to hook in into any method call, including cases when the object a method being called on is unknown by @romalytvynenko in #822
• Remove “dependencies” concept from reference types by @romalytvynenko in #823
• Pagination inference by @romalytvynenko in #826
• Added ability to leave comment to array items in properties defaults by @romalytvynenko in #827
• Add AuthorizationException when Gate::authorize is called by @chrisvanlier2005 in #828
• Allow type inference for @property-read in JsonResource by @chrisvanlier2005 in #830
• String literals decalred with var should be represented as enums not examples by @romalytvynenko in #843
• Save tags to the OpenAPI document’s tags list by @romalytvynenko in #845
• Make sure not to keep schemas extracted from request method calls if parameters are not used by @romalytvynenko in #846
• Fixed accidental closures evaluation when evaluating rules containing closures (like Rule::prohibitedIf) by @romalytvynenko in #847
• Added support for manual documentation on parameters with names defined as class’ consts by @romalytvynenko in #848
• Added type inference for binary operators that return boolean by @romalytvynenko in #849
• Fix error when configuring OpenAPI docs using a callback with DocumentTransformers parameter by @d3radicated in #853

New Contributors

• @SocolaDaiCa made their first contribution in #802
• @olivernybroe made their first contribution in #820
• @vinkla made their first contribution in #821
• @chrisvanlier2005 made their first contribution in #828
• @d3radicated made their first contribution in #853

Error-tolerant rules evaluation

Previously, when Scramble evaluated validation rules (to document request parameters), it could fail due to code that couldn’t be evaluated.

For example, in your update controller method, you might have used data from a real model that exists in the database:

public function update(Request $request, User $user)
{
    $data = $request->validate([
        'level' => ['required', 'integer', Rule::in($user->account->getAvailableLevels())],
    ]);
}

Scramble evaluated such validation rules without sending a real request. So, during documentation generation, it didn’t have access to a “correct” $user model (and what does “correct” even mean without an actual request?). As a result, documentation generation would fail in such cases.

The new release introduces error-tolerant validation rules evaluation. In the example above, Scramble will no longer fail 🚀 This is achieved by evaluating each expression one by one. Scramble processes rules individually, and if it encounters an error — such as with Rule::in($user->account->getAvailableLevels()) — it will simply ignore that rule instead of failing the entire request documentation.

This fixes a whole family of errors where requests weren’t documented. Woohoo! 🎉

• Improved validation rules evaluation to be more tolerant by @romalytvynenko in #809

What’s Changed

• Improve ExportDocumentation command by @lucascbittencourt in #800
• Improved 204 response handling, fixed parameter types templates by @romalytvynenko in #801

New Contributors

• @lucascbittencourt made their first contribution in #800

Documenting query builders defined in called methods

Let’s say you have the following controller that retrieves a list of hotels and returns this list in a response:

class HotelsController
{
    public function __construct(public HotelsListService $hotelsListService) {}
    
    public function index()
    {
        $hotels = $this->hotelsListService->list($request->int('per_page', 15));
        
        return HotelResource::collection()
    }
}

And the following HotelsListService implementation:

class HotelsListService
{
    public function list(int $perPage): QueryBuilder
    {
        return QueryBuilder::for(Hotel::class)
            ->allowedFilters([
                'rooms',
                'name',
                'price',
            ])
            ->allowedSorts([
                'price',
                'rooms',
            ]);
    }
}

Prior to this version Scramble documented only query builders that were constructed in the controller method’s body. But now Scramble analyzes all method calls in the controller’s method so now it can document such cases!

What’s Changed

• Looking for query builder definitions in the called methods

Analyzing calls in controller methods

Ugh, this was a hard one.

Imagine you have the following controller:

class ItemsController
{
    public function __construct(private ItemsRetrievalService $listService) {}
    
    public function __invoke(Request $request)
    {
        $this->listService->ensureCanList();
        
        return ItemResource::collection($this->listService->get());
    }
}

And the following service class:

class ItemsRetrievalService
{    
    /**
     * @throws AuthorizationException
     */
    public function ensureCanList()
    {
        // ... 
    }
    // ...
}

You can see that the ensureCanList method is marked with a @throws AuthorizationException annotation in the PHPDoc. Prior to this update, Scramble did not document such code as potentially producing a 403 response. This was due to how Scramble analyzed the code: it minimized how much source code it parsed into an AST and how much of that AST it traversed. Since ensureCanList’s return type wasn’t used in the controller method’s return type, Scramble never even looked at it.

Starting from version 0.12.17, Scramble analyzes all methods called within controller methods! It still prioritizes performance — it reads only the PHPDoc and skips parsing and traversing the AST if the method’s return type isn’t used in the response.

This means you can now document exceptions using the @throws annotation, and if such a method is called in a controller, Scramble will correctly recognize and document the possible error response.

It might seem like a “nice-to-have” feature, but this update is a stepping stone toward improved type inference in Scramble. Imagine support for things like collect()->map() and beyond — can’t wait to make that happen. Stay tuned!

What’s Changed

• Added configurable layout option for Spotlight Elements UI by @superdejooo in #787
• Fixed scrollbar color in dark color scheme by @romalytvynenko in #790
• Analyzing methods called in controller methods by @romalytvynenko in #793

New Contributors

• @superdejooo made their first contribution in #787

What’s Changed

• Fixed uuid model key compatibility with Laravel 12.x by @sbbjss in #785

New Contributors

• @sbbjss made their first contribution in #785

What’s Changed

• Fixed #[BodyParameter] attribute not adding the information to the parameter by @romalytvynenko in #781

Enum cases description

This version adds support for enum case descriptions — a long-requested and highly upvoted feature!

Now, you can add PHPDoc comments above enum cases, and Scramble will use them as enum descriptions:

enum JobStatus: string
{
    /**
     * When the job application is available.
     */
    case OPEN = 'open';

    /**
     * When the job has been closed.
     */
    case CLOSED = 'closed';
}

This will produce the following JSON schema:

{
    "title": "JobStatus",
    "type": "string",
    "enum": ["open", "closed"],
    "description": "|---|---|\n|`open`|When the job application is available.|\n..."
}

If you use OpenAPI rendering solutions that support it, you can use the x-enumDescriptions extension for case descriptions by setting scramble.enum_cases_description_strategy to extension. In this case, the generated JSON schema will look like this:

{
    "title": "JobStatus",
    "type": "string",
    "enum": ["open", "closed"],
    "x-enumDescriptions": {
        "open": "When the job application is available.",
        "closed": "When the job has been closed."
    }
}

Woohoo!

What’s Changed

• Added enum cases description support by @romalytvynenko in #779
• Fix wrapping when resource instance is used in JsonResponse explicitly by @romalytvynenko in #778

What’s Changed

• Added toJson, toArray, and toResponse methods support on data objects

This release adds complete only and except support on Laravel Data objects. This includes conditional only and except as well as support for onlyProperties and exceptProperties methods defined in data objects classes.

Consider the following example:

public function show(Company $company)
{
    return CompanyData::from($company)->only('id');
}

Now, Scramble will correctly document that this endpoint returns a structure containing only id property:

{
    "type": "object",
    "properties": {
        "id": {
            "type": "integer"
        }
    },
    "required": [
        "id"
    ]
}

What’s Changed

• Added only and except support on Laravel Data objects

What’s Changed

• Fixed breaking change in Laravel Data 4.14 (attributes class was changed)

What’s Changed

• Added Laravel 12.x compatibility

What’s Changed

• Fixed filter parameters becoming nested if dot used in a name

What’s Changed

• Improved exception message when normalizing data type

What’s Changed

• Fix arrays unpacking in arrays passed to ->allow*(...) methods of query builder

What’s Changed

• Added ability to explicitly name schemas
• timacdonald/json-api support (simple features) by @romalytvynenko in #40
• Bump Scramble to 0.12.x by @romalytvynenko in #41