PHPackages                             admin9/laravel-scramble-extensions - 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. admin9/laravel-scramble-extensions

ActiveLibrary[API Development](/categories/api)

admin9/laravel-scramble-extensions
==================================

Scramble extensions for Laravel business-response APIs — auto-wraps OpenAPI docs with success/error envelope, scene-based form request extraction, and filter query parameter extraction.

v0.3.2(4d ago)016MITPHPPHP ^8.3

Since Feb 23Pushed 4mo agoCompare

[ Source](https://github.com/admin9-labs/laravel-scramble-extensions)[ Packagist](https://packagist.org/packages/admin9/laravel-scramble-extensions)[ Docs](https://github.com/admin9-labs/laravel-scramble-extensions)[ RSS](/packages/admin9-laravel-scramble-extensions/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (11)Versions (6)Used By (0)

Laravel Scramble Extensions
===========================

[](#laravel-scramble-extensions)

面向 Mitoop 生态业务接口约定的 [Scramble](https://scramble.dedoc.co/) (OpenAPI 文档生成器) 适配包。

> 这个包不是通用 Scramble 扩展。它服务于使用 `mitoop/laravel-api-response`、`mitoop/laravel-efficient-form-request`、`mitoop/laravel-query-builder` 的项目，把这些业务约定补充到 Scramble 生成的 OpenAPI 文档中。

兼容性
---

[](#兼容性)

PackageVersionPHP`^8.3`Laravel`^13.0`Scramble`^0.13.30`旧版 Laravel/Scramble 项目请继续使用本包 `v0.2.x`。

主要功能：

- 自动将 200 响应包装为统一的业务信封结构 `{success, code, message, data, [meta], request_id}`
- 支持场景化表单请求 (Scene FormRequest) 的参数提取
- 支持 Filter 查询参数自动提取（筛选字段、排序、分页）
- 支持读取数据库字段注释并写入 OpenAPI schema description

各功能模块均可通过配置文件独立开启或关闭；未安装对应 Mitoop 包时，对应模块会自动跳过。

安装
--

[](#安装)

```
composer require admin9/laravel-scramble-extensions
```

发布配置文件：

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

### 可选依赖

[](#可选依赖)

根据你使用的 Mitoop 约定，按需安装对应的包：

```
# 业务响应信封包装
composer require mitoop/laravel-api-response

# 场景化表单请求
composer require mitoop/laravel-efficient-form-request

# Filter 查询参数提取
composer require mitoop/laravel-query-builder
```

配置
--

[](#配置)

配置文件 `config/scramble-extensions.php`：

```
return [
    'response' => [
        'enabled' => true,
        // 控制器需要 use 的 trait，提供 $this->success() 等方法
        'trait' => 'Mitoop\\Http\\RespondsWithJson',
        // 模型命名空间，用于分页响应自动推断模型
        'model_namespace' => 'App\\Models',
        // 从数据库字段注释生成 schema description
        'column_comments' => true,
    ],

    'scene_form_request' => [
        'enabled' => true,
    ],

    'filter' => [
        'enabled' => true,
        'pagination' => [
            'page_size_default' => 15,
            'page_size_max' => 100,
        ],
    ],
];
```

功能说明
----

[](#功能说明)

### 1. 业务响应信封包装 (Response)

[](#1-业务响应信封包装-response)

自动将所有 200 响应包装为统一的业务信封结构。

控制器需要 use 配置中指定的 Mitoop trait（默认 `Mitoop\Http\RespondsWithJson`），通过 `$this->success()`、`$this->error()`、`$this->deny()` 返回响应。

```
class UserController extends Controller
{
    use \Mitoop\Http\RespondsWithJson;

    public function show(User $user)
    {
        return $this->success($user);
    }

    public function index()
    {
        return $this->success(User::paginate());
    }
}
```

生成的 OpenAPI 文档中，标准响应结构为：

```
{
  "success": true,
  "code": 0,
  "message": "",
  "data": { ... },
  "request_id": "uuid7"
}
```

分页响应会额外包含 `meta` 字段：

```
{
  "success": true,
  "code": 0,
  "message": "",
  "data": [ ... ],
  "meta": {
    "pagination": "length_aware",
    "page": 1,
    "page_size": 15,
    "has_more": true,
    "total": 100
  },
  "request_id": "uuid7"
}
```

### 2. 场景化表单请求提取 (Scene FormRequest)

[](#2-场景化表单请求提取-scene-formrequest)

支持 `mitoop/laravel-efficient-form-request`，允许同一个 FormRequest 根据控制器方法名定义不同的验证规则。

扩展会自动查找 FormRequest 上的 `{actionName}Rules()` 方法并提取参数到 OpenAPI 文档。

```
use Mitoop\LaravelEfficientFormRequest\EfficientSceneFormRequest;

class UserRequest extends EfficientSceneFormRequest
{
    // store 方法使用的规则
    public function storeRules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email',
        ];
    }

    // update 方法使用的规则
    public function updateRules(): array
    {
        return [
            'name' => 'string|max:255',
        ];
    }
}
```

```
class UserController extends Controller
{
    public function store(UserRequest $request) { ... }
    public function update(UserRequest $request, User $user) { ... }
}
```

`store` 接口文档会包含 `name`（必填）和 `email`（必填）参数，`update` 接口文档只包含 `name` 参数。

### 3. Filter 查询参数提取 (Filter)

[](#3-filter-查询参数提取-filter)

支持 `mitoop/laravel-query-builder`，自动从 Filter 类中提取筛选字段、排序选项和分页参数到 OpenAPI 文档。

```
use Mitoop\LaravelQueryBuilder\AbstractFilter;

class UserFilter extends AbstractFilter
{
    protected array $allowedSorts = ['created_at', 'name'];

    public function rules(): array
    {
        return [
            'name',
            'email',
            'status',
        ];
    }
}
```

```
class UserController extends Controller
{
    public function index()
    {
        $users = User::filter(UserFilter::class)->paginate();

        return $this->success($users);
    }
}
```

生成的文档会自动包含以下 query 参数：

- `name`、`email`、`status` — 筛选字段
- `sort` — 排序字段，可选值 `created_at`、`name`，前缀 `-` 表示降序
- `page_size` — 每页条数（默认 15，最大 100，可通过配置修改）
- `page` — 页码

### 4. 模型字段注释 (Column Comments)

[](#4-模型字段注释-column-comments)

当模型字段在数据库 schema 中带有 comment 时，扩展会把 comment 写入对应 OpenAPI property 的 `description`。这用于让接口字段说明跟迁移/数据库字段注释保持一致。

该能力依赖数据库驱动能通过 Laravel schema builder 返回 `comment` 字段；不支持字段注释的驱动会安全跳过。

License
-------

[](#license)

MIT

###  Health Score

38

↑

LowBetter than 83% of packages

Maintenance86

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 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 ~32 days

Total

5

Last Release

4d ago

PHP version history (2 changes)v0.1.0PHP ^8.2

v0.3.0PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/89f9c7018c46dc8dcaa27f05cb2cd4ee65b698b38afe4791d2d9e4302fa5013d?d=identicon)[qiyue2015](/maintainers/qiyue2015)

---

Top Contributors

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

---

Tags

laravelswaggeropenapiscramble

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/admin9-laravel-scramble-extensions/health.svg)

```
[![Health](https://phpackages.com/badges/admin9-laravel-scramble-extensions/health.svg)](https://phpackages.com/packages/admin9-laravel-scramble-extensions)
```

###  Alternatives

[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.1k11.2M100](/packages/dedoc-scramble)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

816333.8k3](/packages/defstudio-telegraph)[elegantly/laravel-translator

All on one translations management for Laravel

6333.1k](/packages/elegantly-laravel-translator)[scalar/laravel

Render your OpenAPI-based API reference

67177.6k3](/packages/scalar-laravel)[lettermint/lettermint-laravel

Official Lettermint driver for Laravel

1190.2k1](/packages/lettermint-lettermint-laravel)[tarfin-labs/event-machine

Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail.

199.4k](/packages/tarfin-labs-event-machine)

PHPackages © 2026

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