PHPackages                             zeaven/laravel-easy-suit - 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. [Utility & Helpers](/categories/utility)
4. /
5. zeaven/laravel-easy-suit

ActiveLibrary[Utility & Helpers](/categories/utility)

zeaven/laravel-easy-suit
========================

easy setup package

v3.0.1(2mo ago)068MITPHPPHP ^8.3

Since Jul 9Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/zeaven/laravel-easy-suit)[ Packagist](https://packagist.org/packages/zeaven/laravel-easy-suit)[ RSS](/packages/zeaven-laravel-easy-suit/feed)WikiDiscussions main Synced yesterday

READMEChangelogDependencies (4)Versions (34)Used By (0)

Laravel Easy Suit
=================

[](#laravel-easy-suit)

[![OSCS Status](https://camo.githubusercontent.com/9feadc7b7053c8a6aa2c9fb18a3d6cf7de1d83ba90ff06b7d01d0b04ebb01515/68747470733a2f2f7777772e6f736373313032342e636f6d2f706c6174666f726d2f62616467652f7a656176656e2f6c61726176656c2d656173792d737569742e7376673f73697a653d736d616c6c)](https://www.oscs1024.com/project/zeaven/laravel-easy-suit?ref=badge_small)

这是一个为了方便使用Laravel框架开发api而提供的简单封装套件。集合了参数验证、统一返回格式、错误码定义、Sanctum和JWT、日志、代码生成。

Laravel版本对应版本Larave 13+3.0.0+Laravel 11+2.0.0+Laravel 8+1.0.0+- [Laravel Easy Suit](#laravel-easy-suit)
    - [安装](#%E5%AE%89%E8%A3%85)
    - [Postman 代码生成器](#Postman-%E4%BB%A3%E7%A0%81%E7%94%9F%E6%88%90%E5%99%A8)
    - [Request封装](#Request%E5%B0%81%E8%A3%85)
        - [定义Request对象](#%E5%AE%9A%E4%B9%89Request%E5%AF%B9%E8%B1%A1)
        - [Request对象参数配置](#Request%E5%AF%B9%E8%B1%A1%E5%8F%82%E6%95%B0%E9%85%8D%E7%BD%AE)
    - [全局返回统一格式](#%E5%85%A8%E5%B1%80%E8%BF%94%E5%9B%9E%E7%BB%9F%E4%B8%80%E6%A0%BC%E5%BC%8F)
    - [错误码和异常抛出](#%E9%94%99%E8%AF%AF%E7%A0%81%E5%92%8C%E5%BC%82%E5%B8%B8%E6%8A%9B%E5%87%BA)
        - [错误码定义](#%E9%94%99%E8%AF%AF%E7%A0%81%E5%AE%9A%E4%B9%89)
        - [异常抛出](#%E5%BC%82%E5%B8%B8%E6%8A%9B%E5%87%BA)
    - [注解日志](#%E6%B3%A8%E8%A7%A3%E6%97%A5%E5%BF%97)
        - [在控制器使用日志](#%E5%9C%A8%E6%8E%A7%E5%88%B6%E5%99%A8%E4%BD%BF%E7%94%A8%E6%97%A5%E5%BF%97)
        - [内置注解模板变量](#%E5%86%85%E7%BD%AE%E6%B3%A8%E8%A7%A3%E6%A8%A1%E6%9D%BF%E5%8F%98%E9%87%8F)
    - [用户认证](#%E7%94%A8%E6%88%B7%E8%AE%A4%E8%AF%81)
        - [配置](#%E9%85%8D%E7%BD%AE)
        - [自动刷新Token](#%E8%87%AA%E5%8A%A8%E5%88%B7%E6%96%B0Token)
        - [Sanctum认证](#Sanctum%E8%AE%A4%E8%AF%81)
        - [使用Sanctum认证](#%E4%BD%BF%E7%94%A8Sanctum%E8%AE%A4%E8%AF%81)
        - [JWT认证](#JWT%E8%AE%A4%E8%AF%81)
            - [安装JWT第三方包](#%E5%AE%89%E8%A3%85JWT%E7%AC%AC%E4%B8%89%E6%96%B9%E5%8C%85)
            - [配置JWT](#%E9%85%8D%E7%BD%AEJWT)
        - [使用JWT认证](#%E4%BD%BF%E7%94%A8JWT%E8%AE%A4%E8%AF%81)
    - [ResponseMapper 资源映射](#ResponseMapper-%E8%B5%84%E6%BA%90%E6%98%A0%E5%B0%84)
    - [Model扩展](#Model%E6%89%A9%E5%B1%95)
        - [开启分页简化](#%E5%BC%80%E5%90%AF%E5%88%86%E9%A1%B5%E7%AE%80%E5%8C%96)
        - [开启扩展](#%E5%BC%80%E5%90%AF%E6%89%A9%E5%B1%95)
            - [withs](#withs)
            - [selectWhen](#selectWhen)
            - [whereWhen](#whereWhen)
            - [whenFilled](#whenFilled)
            - [betweenWhen](#betweenWhen)
            - [likeWhen](#likeWhen)

*[Table of contents generated with markdown-toc](http://ecotrust-canada.github.io/markdown-toc/)*

安装
--

[](#安装)

```
composer require zeaven/laravel-easy-suit
```

### 发布

[](#发布)

```
php artisan vendor:publish --provider=Zeaven\\EasySuit\\ServiceProvider
```

Postman 代码生成器
-------------

[](#postman-代码生成器)

使用前先在.env文件添加postman的apiToken：

POSTMAN\_API\_TOKEN=xxx

然后执行 artisan pm:run

[![pm:run使用](https://raw.githubusercontent.com/zeaven/laravel-easy-suit/main/image/pm.png)](https://raw.githubusercontent.com/zeaven/laravel-easy-suit/main/image/pm.png)

postman接口定义如下:

[![postman接口定义](https://raw.githubusercontent.com/zeaven/laravel-easy-suit/main/image/postman.png)](https://raw.githubusercontent.com/zeaven/laravel-easy-suit/main/image/postman.png)

生成的控制器代码： [![controller](https://raw.githubusercontent.com/zeaven/laravel-easy-suit/main/image/controller.png)](https://raw.githubusercontent.com/zeaven/laravel-easy-suit/main/image/controller.png)

生成的Request代码： [![request](https://raw.githubusercontent.com/zeaven/laravel-easy-suit/main/image/request.png)](https://raw.githubusercontent.com/zeaven/laravel-easy-suit/main/image/request.png)

其他文件不一一展示，接口代码生成后，只需要配置参数验证规则，和在Logics目录编写业务逻辑代码即可

路由配置自动添加，但是中间件需要自行配置

同时需要修改bootstrap/app.php的路由代码如下：

```
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
        then: function () {
            Route::configRoute('api', 'api');
        },
    )
```

你也可以按照configRoute方法的写法定义路由：

```
    Route::middleware('api')
                ->prefix('api')
                ->name('api.')
                ->namespace("App\\Http\\Controllers\\Api")
                ->group(base_path('routes/api.php'));
```

Request封装
---------

[](#request封装)

BaseRequest继承于FormRequest，增加一个rule方法配置参数规则。

### 定义Request对象

[](#定义request对象)

```
use Zeaven\EasySuit\Http\Requests\BaseRequest;

class LoginRequest extends BaseRequest
{
    /**
     * 返回参数验证规则.
     *
     * @return array
     */
    protected function rule(): array
    {
        return [
            // 用户名
            'username' => ['rule' => 'required'],
            // 密码
            'password' => ['rule' => 'required|min:6']
        ];
    }
}
```

Request对象提供两个方法获取参数：params和values，*注意：未配置的参数是无法通过这两个方法获取的*

```
[$username, $password] = $request->values();
// 或
[$username] = $request->values(['username']);
// 或
[$password, $username] = $request->values(['password', 'username']);

// 获取key/value数组
$params = $request->params();
// $params = ['username' => 'xxx', 'password' => 'xxx']
// 或
$params = $request->params(['username']);
// 或
// $params = ['username' => 'xxx']
$params = $request->params(['username', 'password']);
// $params = ['username' => 'xxx', 'password' => 'xxx']
```

### Request对象参数配置

[](#request对象参数配置)

rule方法返回参数的配置，完整配置字段如下：

```
[
    'username' => [
        'rule' => 'required',
        'default' => 'admin',
        'type' => 'string',
        'as' => 'login_name'
    ],
    'remember' => true, // 等同于 'remember' => ['default' => true]
    'password'  // 等同于‘password’ => ['default' => null]
]
```

> 1. rule 与Laravel的表单验证规则一致；
> 2. default 默认值；
> 3. type 参数类型，可选值有：int、float、bool、array(json)、date、ip、url、split(将字符串转以逗号分割成数组)；
> 4. as 别名，使用values()方法返回的key值；

全局返回统一格式
--------

[](#全局返回统一格式)

在使用前需要先添加路由中间件：

```
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->api(append:[
                'throttle:api'
            ],
            prepend: [
                \Zeaven\EasySuit\Http\Middleware\GlobalResponse::class,
                \Zeaven\EasySuit\Annotations\AnnoLogMiddleware::class,
            ]);
    }
```

在easy\_suit.php配置文件中有如下默认配置:

```
'global_response' => [
    'fields' => [
        'code' => 'code',
        'data' => 'data',
        'message' => 'msg',
        'error' => false, // error只有在debug环境下有效
    ],
    'exclude' => [
        'horizon/*',
        'laravel-websockets/*',
        'broadcasting/*',
        '*/export/*',
        '*/pusher/auth',
        '*/pusher/auth',
        'web/*',
    ]
],
```

> fields 指定返回的字段，以及字段名称，如果定义为false则不显示 exclude 可定义排除的路由

在控制器中 调用ok()全局方法，返回即可。

错误码和异常抛出
--------

[](#错误码和异常抛出)

### 错误码定义

[](#错误码定义)

在error\_code.php配置文件中定义错误码信息，下面的规则只是参考，至于你喜欢多少位的错误码，完全由你决定

错误码会发布到lang目录下，因为它是支持多语言的。

```
/**
 * 错误码定义样例，请不要在这里定义错误码！应在对应的语言包目录下创建error_code.php文件！
 * 错误码以十六进制方式定义，如f00000:
 * -- 第1位：项目 f全局、1~e自行分项目，如1ios、2android、3web、4小程序
 * -- 第2-3位：模块 00全局、其他数字自行定义，如01登录、02订单、03钱包
 * -- 第4-5位：错误码，如00~ff都可以使用
 * -- 第6位：提示码，0忽略错误、1客户端弹窗提示、2客户端toast提示
 * 出现error_code=0,则后台未知错误
 *
 * 比如定义ios端登录模块错误码： 101012 => '用户名错误'， 101022 => '用户密码错误'
 */

return [
    '401'    => '未授权',
    '500'    => '查询出错',
    'f00002' => 'token已过期',
    'f00012' => '用户不存在',
    'f00022' => 'token无效',
    'f00032' => '缺少登录信息',
];
```

### 异常抛出

[](#异常抛出)

使用全局方法在你需要的地方抛出异常

```
// 直接抛出错误码
throw_e(0x000001);
throw_e(401);
// 抛出异常信息
throw_e('异常信息');
// 指定错误信息和错误码
throw_e('异常信息', 0x000001);
// 空条件抛出
throw_empty($user, 0x000001);   // $user变量为空则抛出异常
throw_empty($user, '异常信息');   // 同上
throw_empty($user, '异常信息', 0x000001);   // 同上
// 判断条件抛出
throw_on($user->status === -1, 0x000001);
// 或
throw_on($user->status === -1, '异常信息');
throw_on($user->status === -1, '异常信息', 0x000001);
```

所有异常抛出方法的最后一个参数可以传入一个数组，用于本地化参数替换，[替换翻译字符串中的参数](https://learnku.com/docs/laravel/9.x/localization/12232#replacing-parameters-in-translation-strings)

注解日志
----

[](#注解日志)

注解日志采用控制器方法添加注解的方式实现，默认api中间件组自动添加 ，如果其他路由需要，请在使用前需要先添加路由中间件：

```
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->web(
            prepend: [
                \Zeaven\EasySuit\Annotations\AnnoLogMiddleware::class,
            ]);
    }
```

日志默认使用laravel的日志服务，你可以在easy\_suit.php配置文件中修改自定义的处理程序，以及是否开启日志

```
    'anno_log' => [
        'enable' => env('EASY_SUIT_ANNO_LOG', true),
        'handler' => MyAnnoLogHandler::class
    ],
```

**MyAnnoLogHandler 对象必须实现接口 \\Zeaven\\EasySuit\\Annotations\\AnnoLogHandler;**

### 在控制器使用日志

[](#在控制器使用日志)

当此方法有请求时，日志会在返回用户结果后保存

```
    use Zeaven\EasySuit\Annotations\AnnoLog; // 必须引用注解命名空间

    #[AnnoLog(tpl:"{mobile},审核提现,订单号{order_no},签名{sign}")]
    public function index(TestRequest $request)
    {
        // 设置日志模板变量
        anno_log(['order_no' => 'test', 'sign' => 'sign']);
        // 或
        anno_log('order_no', 'test');
        anno_log('sign', 'sign');
    }
```

### 内置注解模板变量

[](#内置注解模板变量)

在用户登录状态下，登录用户模型的缓存字段信息将自动添加到模板变量，可直接使用，如：

- uid
- mobile
- username
- nickname

用户认证
----

[](#用户认证)

### 配置

[](#配置)

在easy\_suit.php文件中

```
    'auth' => [
        'sanctum' => true,
        'jwt' => [
            'enable' => true,
            'guard' => 'jwt'
        ],
    ],
```

### 自动刷新Token

[](#自动刷新token)

内置的Authenticate对Token验证的同时，如果token超过刷新周期，

则会自动刷新对应的Token，通过响应头下发给客户端，所以客户端应该在请求成功回调中，判断响应头是否包含“Authorization”字段，有的话，记得刷新本地Token。

```
$axios.onResponse((response) => {
    // 刷新token
    if ('authorization' in response.headers) {
      // eslint-disable-next-line no-unused-vars
      const [_, token] = response.headers.authorization.split(' ')
      store.commit('SET_TOKEN', token)
    }
    return Promise.resolve(response.data)
  })
```

**注：自动刷新token必须在客户端请求中添加Authorization请求头**

### Sanctum认证

[](#sanctum认证)

在配置文件中启用Sanctum认证后，将会使用内置的Authenticate接管认证过程，

同时为Sanctum认证增加自动刷新token功能，具体配置项如下；

> ```
>     'expiration' => 20160,  // 两周过期时间
>     'refresh_ttl' => 60,    // 一个小时刷新一次token
>     'refresh_grace_ttl' => 5, // 刷新token的灰色时间，防止同一token并发多个请求刷新多次
>     'remove_refresh_expire_token' => true,  // 是否移除已刷新的token
> ```
>
>
>
> 如上配置，token将会在每小时刷新一次，每次有效期是两周 即两周内有访问，token有效期就可以一直往后延 每次刷新后，原来的token也可以选择是否需要删除

### 使用Sanctum认证

[](#使用sanctum认证)

在路由配置中添加auth中间件

```
Route::middleware('auth:sanctum')->group(function () {
    // 你的路由
});
```

### JWT认证

[](#jwt认证)

在配置文件中启用JWT认证后，将会使用内置的Authenticate接管认证过程，

同时为JWT认证增加自动刷新token功能。

#### 安装JWT第三方包

[](#安装jwt第三方包)

Laravel 9.x 不支持 tymon/jwt-auth 包，但可以指定开发版

```
composer require "tymon/jwt-auth:dev-develop"
```

#### 配置JWT

[](#配置jwt)

按照tymon/jwt-auth配置，在auth.config添加jwt的守卫配置后

```
    'guards' => [
        'web' => [
            'driver' => 'session',
            'provider' => 'users',
        ],
        'jwt' => [
            'driver' => 'jwt',
            'provider' => 'users',
        ]
    ],
```

在easy\_suit.php配置文件中，也把auth.jwt.guard改成你添加的守卫名称，这里都是"jwt"

### 使用JWT认证

[](#使用jwt认证)

在路由配置中添加auth中间件

```
Route::middleware('auth:jwt')->group(function () {
    // 你的路由
});
```

ResponseMapper 资源映射
-------------------

[](#responsemapper-资源映射)

对应的是Laravel的*API 资源*，使用的场景不多，所以采用配置的方式将数据转换成JSON格式。

#### Mapper生成

[](#mapper生成)

可以通过artisan命令生成Maaper文件

```
php artisan gen:mapper user/info
// 将在路径生成文件 App/Http/ResponseMappers/User/InfoMapper.php