#scrambledrop: Scramble 0.13.x

October 24, 2025

Full type inference, more control over return types documentation, and closure-based routes support.

Hey Laravel community!

I’m excited to announce the v0.13.x release. This version brings support for full type inference for types coming from vendors! These are the types coming from PHPDoc and supported by package authors. I cannot express how excited I am!

Scramble is a Laravel API documentation generator that creates docs without requiring PHPDoc annotations: https://scramble.dedoc.co/.

Starting from Laravel 11.x (and especially from 12.x), Laravel comes with great and accurate PHPDoc annotations. With Scramble supporting these types, you’ll enjoy focusing more on the app codebase rather than writing type annotations.

While this release has no breaking changes itself, the resulting OpenAPI document may be more accurate for your specific application, and hence may be considered as the one containing breaking changes. Due to this, I’ve decided to mark this release as 0.13.x. It means that you’ll need to explicitly update the version in composer.json if you rely on ^0.12.0 or earlier versions.

Let’s dive into specific examples so maybe I can make you as excited as I am!

Full type inference

Since the initial release, Scramble has inferred types solely by analyzing the source code. This is a very time-consuming process: to analyze the source, it must first be parsed and turned into an AST (a tree-like structure that allows programmatic interaction with the code). Then, the AST must be traversed to infer types. Just creating the AST from the source code takes about 50% of the total time required to generate the OpenAPI documentation. To save time, I didn’t analyze source code originating from vendor.

In the past year, Laravel has made significant improvements to PHPDoc types for static analysis, so I couldn’t postpone it any longer and finally implemented support for analyzing types coming from vendors. When analyzing vendor classes, Scramble doesn’t process the AST — it only reads the PHPDoc, which keeps it fast.

I will make a fresh app installation to demonstrate the brand-new type inference. This app will be a simple appointment booking system.

After creating a new Laravel 12.x app, installing Scramble, and running php artisan install:api, let’s create the Appointment model, a migration, and a route for listing all the appointments:

use App\Models\Appointment;

Route::get('/appointments', function (Request $request) {
    $items = Appointment::query()
        ->where('status', $request->string('status'))
        ->get();

    return $items;
});

In this case, Scramble can infer the type of $items: it is a collection of appointments, specifically: Illuminate\Database\Eloquent\Collection<int, App\Models\Appointment>!

This gives nice documentation just by analyzing the source, without any additional annotations:

This works thanks to all PHPDoc type annotations Laravel has.

Now, let’s create a new model, Client, and create hasMany relationship on it – a client can have many appointments.

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class Client extends Model
{
    public function appointments(): HasMany
    {
        return $this->hasMany(Appointment::class);
    }
}

Now, when working with a Client instance, you can get all the client’s active appointments via the relation method:

$client = Client::findOrFail($clientId);

$recentActiveAppointment = $client->appointments()
    ->where('status', 'active')
    ->orderBy('id', 'desc')
    ->first();

// Scramble knows the type here: `Appointment|null`.
return $recentActiveAppointment;

Thanks to PHPDoc annotations across the Laravel codebase, Scramble can infer the type of $recentActiveAppointment without you adding any annotations.

This also works beautifully with collections.

Here is the real world case: https://github.com/dedoc/scramble/discussions/949

$filesystems = FileSystem::query()->get();

return response()->json([
    'filesystems' => $filesystems->map(function (FileSystem $filesystem) {
        return [
            'id' => $filesystem->id,
            'name' => $filesystem->name,
            'owner' => [
                'name' => $filesystem->owner->name,
            ],
            'size' => $filesystem->size,
            'used' => $filesystem->used,
        ];
    }),
]);

With the new Scramble’s type inference system it will just work.

This is something I’m very excited about and what I’ve always wanted Scramble to be – a tool that lets you focus on your application’s logic while effortlessly having a great API documentation.

More control over return types

When you write functions and methods, Scramble analyzes the AST (this is the code representation suitable for analysis) to determine the return type. However, Scramble is not perfect, and in some cases, it may not infer the type, or it may infer a type that’s too broad.

Now, Scramble also checks the type hint and PHPDoc @return type annotation. When some of them are present, Scramble ensures that the type inferred from the AST is actually one that can be returned from this method. If not, the annotated type will be used.

Closure-based routes support

As you may have noticed from the previous examples, the routes there are defined using closures.

Previously, Scramble only supported controller-based routes. Now, the routes defined using closures also get their share of love and are documented automatically.

Closure-based routes support all the attributes (for manual parameters, headers, responses, etc.) that are supported by controller-based methods.

So, right after creating a new Laravel 12.x app, installing Scramble, and running php artisan install:api, this is the api.php you’d get:

<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::get('/user', function (Request $request) {
    return $request->user();
})->middleware('auth:sanctum');

And this is the documentation Scramble generates just from this code:

0.13.x comes with a great number of type inference system improvements. Now it is more predictable and much more accurate thanks to the vendor type inference.

I am so excited about this and hope you are too.

Give the new Scramble a go and let me know what you think!