hesb/laravel-plus

Laravel-Plus is an efficient Laravel extension package designed to enhance development productivity. It integrates powerful annotation handling and practical helper classes, making the development of Laravel applications more convenient and flexible.

2.0.1 2025-03-05 03:29 UTC

Requires

• php: ^8.0
• laravel/framework: ^11.0
• netresearch/jsonmapper: ~4.0.0
• phpdocumentor/reflection-docblock: ^5.0
• swagger-api/swagger-ui: ^4
• zircote/swagger-php: ^4.5

MIT

• tangcheng

README

介绍

基于 tw2066/dto tw2066/api-docs 框架改进而来，特别鸣谢tw2066/dto给的灵感

运行环境

• php >= 8.0
• lavarel 11.0

安装

composer require hesb/laravel-plus

配置工作

1. 在 web.php 添加代码

use Hesb\LaravelPlus\EasyCommand;

EasyCommand::register();

1. 从composer组件复制doc/api_docs.php到项目config目录下

使用说明

控制器配置

<?php

declare(strict_types=1);
namespace App\Http\Controllers\Api\Test;

use App\Http\Dto\Api\Test\TestBodyDto;
use App\Http\Dto\Api\Test\TestFormDto;
use App\Http\Dto\Api\Test\TestQueryDto;
use App\Http\Vo\DataSubmitVo;
use App\Http\Vo\Test\TestQueryVo;
use App\Logic\Api\User\UserLogic;
use Hesb\LaravelPlus\Annotation\Api;
use Hesb\LaravelPlus\Annotation\ApiOperation;
use Hesb\LaravelPlus\Annotation\ApiResponse;
use Hesb\LaravelPlus\Annotation\Contracts\RequestBody;
use Hesb\LaravelPlus\Annotation\Contracts\RequestFormData;
use Hesb\LaravelPlus\Annotation\Contracts\RequestQuery;
use Hesb\LaravelPlus\Annotation\Contracts\Valid;
use Hesb\LaravelPlus\Annotation\Controller;
use Hesb\LaravelPlus\Annotation\GetMapping;
use Hesb\LaravelPlus\Annotation\Inject;
use Hesb\LaravelPlus\Annotation\PostMapping;
use Hesb\LaravelPlus\Traits\Injectable;


#[Api(tags: '测试')]
#[Controller(prefix:"/api/api/test/test")]
class TestController
{
    #[ApiOperation('测试query')]
    #[GetMapping(path: 'query')]
    #[ApiResponse(TestQueryVo::class)]
    public function query(#[RequestQuery] #[Valid] TestQueryDto $dto){
        //逻辑层高处理对
        $params = get_object_vars($dto);
        $params['time'] = time();
        $params['token'] = csrf_token();
        //逻辑层返回数组
        //根据响应对象，约束响应数据
        return json_encode($params);
    }

    #[ApiOperation('测试body')]
    #[PostMapping(path: 'body')]
    #[ApiResponse(DataSubmitVo::class)]
    public function body(#[RequestBody] #[Valid] TestBodyDto $dto){
        //逻辑层返回数组
        $result = $this->logic->add($dto);
        //根据响应对象，约束响应数据
        return $result;
    }

    #[ApiOperation('测试form')]
    #[PostMapping(path: 'form')]
    #[ApiResponse(DataSubmitVo::class)]
    public function form(#[RequestFormData] #[Valid] TestFormDto $dto){
        var_dump($dto);
        $params = [];

        $params['time'] = time();
        //逻辑层返回数组
        //根据响应对象，约束响应数据
        return response()->json($params);
    }
}

创建简单DTO

#[ApiModel('query管理')]
class TestQueryDto
{
    #[ApiModelProperty('查询ID')]
    #[Required]
    public string $query_id;
}

创建复合DTO

#[ApiModel('body管理')]
class TestBodyDto
{
    #[ApiModelProperty(value:'用户信息',required: true)]
    #[Required]
    public UserDto $user;

    /**
     * @var \App\Http\Dto\Api\Test\TestBodyDetailDto []
     */
    #[ApiModelProperty(value:'明细列表',required: true)]
    public array $detail_list;

    #[ApiModelProperty(value:'创建日期')]
    #[Date]
//    #[After("2025-1-1")]
//    #[DateFormat("Y-m-d H:i:s")]
    public string $create_date;

//    #[ApiModelProperty(value:'body数组')]
//    #[Arr]
//    public array $arr;
//
//    #[ApiModelProperty(value:'url地址')]
//    #[Url]
//    public string $url;

//    #[ApiModelProperty(value:'ip地址')]
//    #[Ip]
//    public string $ip;

//    #[ApiModelProperty(value:'数字')]
//    #[Numeric]
//    public string $num;

//    #[ApiModelProperty(value:'服务协议')]
//    #[Accepted]
//    public string $accept;

//    #[ApiModelProperty(value:'字符串')]
//    #[Size(value:5)]
//    public string $str;
}

---

#[ApiModel('明细管理')]
class TestBodyDetailDto
{
    #[ApiModelProperty(value:'明细id',required: true)]
    #[Required]
    public string $detail_id;

}
---

#[ApiModel('用户管理')]
class UserDto
{
    #[ApiModelProperty(value:'昵称',required: true)]
    #[Required]
//    #[RequiredIf(['user.sex'=>'1'])]
//    #[Same("tc")]
    public string $nick_name;

    #[ApiModelProperty('手机号')]
    #[Regex(value:"/^(13[0-9]|14[579]|15[0-3,5-9]|16[6]|17[0135678]|18[0-9]|19[89])\d{8}$/")]
    public String $mobile;

    #[ApiModelProperty('邮箱')]
//    #[Email]
    public string $email;

    #[ApiModelProperty('年龄')]
//    #[Between(min:18,max:60)]
//    #[Min(18)]
    #[Required]
    public string $age;

    #[ApiModelProperty('性别: 1 男, 2 女')]
    #[In(['1','2'])]
//    #[NotIn(['1','2'])]
    public string $sex;
}

注意事项

1. 无论控制器和dto都要在类上加注解,否则无法扫描
2. 一个方法，不能同时注入RequestBody和RequestFormData,参照java springboot路由注解

效果

1. 通过命令生成swagger文档

   php artisan swagger:init
   

2. 访问 当前项目域名 + /swagger

图片如下

1. 根据dto配置自动校验 图片如下

参考https://gitee.com/hesb/laravel-test.git 配置