# Dcat Admin 整合插件快速开发版本_dcat_faster

**Repository Path**: fitop/dcat-faster

## Basic Information

- **Project Name**: Dcat Admin 整合插件快速开发版本_dcat_faster
- **Description**: 旨在能更快更方便的开始和完成中小型项目，基于Dcat admin框架，整合了支付（yansongda-pay），短信(easy-sms)，微信(easywechat)，以及很多常用方法封装，对dcat的一些改进
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 20
- **Forks**: 8
- **Created**: 2022-10-10
- **Last Updated**: 2025-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### dcat-faster 基于 Dcat Admin 整合，旨在让你快速入门dcat admin以及常用第三发接口
#### 已集成插件文档
- **[Laravel10 文档](https://learnku.com/docs/laravel/10.x)**
- **[Dcat Admin文档](https://learnku.com/docs/dcat-admin/2.x)**
- **[overtrue/pinyin 汉字转拼音](https://github.com/overtrue/pinyin)**
- **[easy-excel excel导入导出](https://gitee.com/lirko/easy-excel)**
- **[php-snowflake 雪花算法唯一ID](https://github.com/godruoyi/php-snowflake)**

#### 按需集成插件文档
- **[Yansongda 微信支付和公众号支付(v3)](https://pay.yansongda.cn/docs/v3/)**
- **[qiniu-laravel-storage 七牛云](https://gitee.com/fitop/qiniu-laravel-storage)**
- **[overtrue/easy-sms 短信插件](https://gitee.com/mirrors_overtrue/easy-sms)**
- **[overtrue/wechat 微信相关接口(v5)](https://easywechat.com/docs/5.x/overview)**
- **[intervention/image 图片处理](https://github.com/Intervention/image)**

###  安装步骤
#### 安装运行环境
推荐使用宝塔面板一键安装，基础环境如下：
- PHP8.1+
- Nginx 1.15 +
- MySQL5.7-8.0

需要开启的PHP扩展如下：fileinfo、bcmath

需要解除禁用的函数：putenv、proc_open

#### 配置项目
1. 在nginx中将网站目录指向/public目录下，配置laravel伪静态
~~~
location / {
    try_files $uri $uri/ /index.php?$query_string;
}
~~~
2. 配置.env文件中的数据库配置（DB_开头），切换到项目目录，再依次运行：
~~~  
composer install 
php artisan admin:publish
php artisan admin:install
php artisan key:generate

//以下为创建admin_config表并填充数据和菜单
php artisan migrate
php artisan db:seed
~~~
#### 演示站点
默认账号：admin 默认密码 ：admin
- **[Dcat官方演示站点: http://103.39.211.179:8080/admin/](http://103.39.211.179:8080/admin/auth/login)**


### 微信支付/支付宝支付
1.需安装 `yansongda/pay` 依赖包
~~~
composer require yansongda/pay:~3.7.0 -vvv
composer require guzzlehttp/guzzle:^7.0 
~~~
2.在.env或config/pay.php中配置支付参数

3.用法举例(微信公众号支付v3)，
~~~
$config=config('pay');
\Yansongda\Pay\Pay::config($config);
$order = [
    'out_trade_no' => time().'', //需为 string 类型
    'description' => 'subject-测试',
    'amount' => [
        'total' => 1,
    ],
    'payer' => [
        'openid' => 'onkVf1FjWS5SBxxxxxxxx',
    ],
];
$result = \Yansongda\Pay\Pay::wechat()->mp($order);
~~~
详细用法请参考：**[Yansongda 微信支付和公众号支付(v3)](https://pay.yansongda.cn/docs/v3/)**

### 微信公众号/小程序接口相关
1.安装 `overtrue/wechat` 依赖包
~~~
composer require overtrue/wechat:~5.0 -vvv
~~~
2.在.env或config/wechat.php中配置微信相关参数
3.用法举例
~~~
function applet_login() {
    //小程序授权登录
    $config = config("wechat.mini_program.default");
    $app = \EasyWeChat\Factory::miniProgram($config); 
    try {
        $res = $app->auth->session($request->input("code", ''));
        if (isset($res['openid'])) {
            //session_key建议不要返回给前端
            session("session_key", $res['session_key']);
            $user=\App\Models\User::where('openid',$res['openid'])->first();
        } else {
            //授权登录失败
        }
    } catch (\Exception $e) {
        //配置错误时排除异常
       
    }

}
~~~
详细用法请参考：**[overtrue/wechat 微信相关接口(v5)](https://easywechat.com/docs/5.x/overview)**

### 短信接口
1.安装 `overtrue/wechat` 依赖包
~~~
composer require "overtrue/easy-sms"
~~~
2.在.env或config/easysms.php中配置短信相关参数

3.用法举例（阿里云短信）
~~~
// easy-sms 用法 
$config=config("easysms");
$easySms = new \Overtrue\EasySms\EasySms($config);
try{
    $res= $easySms->send($mobile, [
        'content'  => '您的验证码是028010，请勿泄露给他人。',
        'template' => $template_code,//模板CODE
        'data' =>['verify_code'=>'028010'],
    ]);
    //发送成功
}catch(\Exception $e){
    //发送失败
}

//1.助手函数，app/Tools/helper.php
send_sms("login",'18500000000',['code'=>'028666'],true); //发送验证码
check_sms_code("login",'18500000000','028666'); //校验验证码是否正确
~~~
详细用法参考：**[overtrue/easy-sms 短信插件](https://gitee.com/mirrors_overtrue/easy-sms)**
 
## 图片/文件上传
#### 1.七牛云上传
安装`zgldh/qiniu-laravel-storage`插件，
~~~
composer require zgldh/qiniu-laravel-storage:9.0
~~~
使用laravel文件系统进行上传
~~~
//方式1
$request->file("file")->storeAs('uploads/images/202502/',  'abc.jpg','qiniu');;
//方式2
QiniuStorage::disk('qiniu')->put('uploads/images/202502/123.jpg','图片文件');
~~~
详细用法参考：**[qiniu-laravel-storage 七牛云](https://gitee.com/fitop/qiniu-laravel-storage)**
#### 2.自定义上传
~~~ 
	//后台自定义接收端参考 AdminAttachmentController@upload
	//单图表单上传 
	$form->image('avatar',"商品缩略图")
		->accept('jpg,png,gif,jpeg,bmp,jpg', 'image/*')
		->url("upload"); //指定上传链接
	//多图表单上传
	$form->multipleImage('images', '商品轮播图')
	    ->sortable()
		->saveAsJson();
	$form->multipleImage('images', '商品轮播图')->limit(5)
		->accept('jpg,png,gif,jpeg,bmp,jpg', 'image/*') 
		->url("upload")
		->saving(function ($paths) {
			return implode(',', $paths);//指定用逗号拼接保存
		});

	//列表预览，单图多图通用
	$grid->column('images')->display(function ($pictures) {
		return explode(",", $pictures);//指定用逗号分割
			//  return json_decode($pictures, true);
	})->image(null, 50, 50);
~~~  

## Excel导入、导出

### 导入
1. 上传Excel请参考工具类：\App\Helpers\ImportTool 和 \resources\views\admin\tools\import.blade.php
2. Excel导入举例：
~~~
use App\Admin\Grid\ImportTool;
use Dcat\Admin\Traits\HasUploadedFile;
use Dcat\EasyExcel\Excel; 

class UserController extends AdminController {
	use HasUploadedFile;
	protected function import(Request $request) {
		//先保存到本地
		$disk = $this->disk("local");
		if (!$request->hasFile('file')) {
			return show(500, "未检测到文件");
		}
		$file = $request->file("file");
		$newName = date("Ym") . "/" . md5(uniqid() . mt_rand(1000, 9999)) . "." . $file->getClientOriginalExtension();
		$result = $disk->putFileAs("uploads/files", $file, $newName);
		$path = "/uploads/files/" . $newName;
		$sheet = Excel::import(public_path($path))->sheet(0)->toArray();
		var_dump($sheet);
	}
}
~~~
### Excel导出
1. grid列表快速导出：
~~~ 
$titles = [
    'order_no' => '订单号', 'goods_name' => '商品信息','money'=>'支付金额','status'=>'订单状态'
];
$status=['0'=>'未支付','1'=>'已支付'];
$grid->export()->titles($titles)->rows(function ($rows)use($status) {
    foreach ($rows as $index => &$row) {
        $row['status'] = $status[$row['status']]??'未支付';//修改导出接口内容
    }

    return $rows;
});
~~~
2. 自定义导出可使用`dcat/easy-excel`，参考文档：https://gitee.com/lirko/easy-excel



## 助手函数/工具类
### 列表快速弹框（跳过RawAction）
dcat admin 的列表在新增一个弹框页面必须先追加一个RawAction操作，每一个弹框都去创建一个action有点麻烦，故写了两个通用的action，再多的弹框用着两个action就够了。
- LazyFormAction 列表操作栏快速追加懒加载表单(app/Admin/Actions)
- ModalAction 列表操作栏快速追加自定义URL的弹框(app/Admin/Actions)

~~~
use App\Admin\Actions\LazyFromAction;
use App\Admin\Actions\ModelAction;
$grid->actions(function(Actions $actions){
    //行操作直接打开异步表单
    $action->append(new LazyFormAction(OrderSendForm::class,['id'=>$action->row->id],'订单发货','feather icon-clock'));
    
    //行操作直接打开自定义链接
    $actions->append(mew ModelAction(admin_url('order/info')),['id'=>$actions->row->id],'订单详情',null,['800px','500px']);
}
~~~ 
### 其他工具目录：app/Tools/
- API接口返回json格式
~~~
    show(403,'暂无修改权限',$data);   //自定义code返回
    show_success('操作成功',$data);  //快速返回成功，code为200，
    show_error('操作失败',$data);    //快速返回失败信息，code为500
~~~
参考返回结果格式:
~~~
{
    "code":200,
    "data":null,
    "msg":"success",
    "encrypt":false
}
~~~

- admin_config() 获取配置，此操作需要导入admin_config表默认值，运行：
~~~
php artisan db:seed
~~~
获取后台的表单关联后台的分组配置表单，此方法会用缓存
~~~
    admin_config("withdraw_percent");
~~~
- unique_no() 雪花算法生成16位唯一单号
~~~
    unique_no();    //年份开头的20位单号
    unique_no("TK",mt_rand(1000,9999)); //追加自定义前缀和后缀
~~~
- validate_form() 快速验证用户提交数据
~~~
    validate_form([
        "mobile|手机号" => "required|size:11",
        "name|姓名" => "required"
    ]);
~~~
- children_tree() 递归构造二叉树
~~~
    $list=Category::->select('id','pid','name')get()->toArray();
    $list=children_tree($list);
~~~
- curl_post(),curl_get() 发送CURL请求
~~~
    curl_post($url,['name'=>'G'],['ContentType:application/json']);
    curl_get($url); 
~~~
- rand_char() 生成随机字符串，数字
~~~
    rand_char(8,5);
~~~
- number2chinese() 数字转汉字
~~~
    number2chinese(25); // 25 > 二十五
~~~
- distance_api(),distance_line() 获取两地点的距离
~~~
    distance_api($lat1,$long1,$lat2,$long2,'walking'); //腾讯地图接口
    distance_line($lat1,$long1,$lat2,$long2);       //球体计算距离
~~~
- distance_raw(); MySQL中生成坐标距离计算的列
~~~
    distance_raw($latitude,$longitude);
~~~
- send_sms() 发送阿里云短信 ,需要在.env 和/config/easysms.php配置短信
~~~
    send_sms("notice",185xxxx2333,['order_no'=>'xxxxx','status'=>'已发货']);//发送通知类短信
    send_sms("login",185xxxx2333,['code'=>mr_rand(100000,999999)],true);//发送登录验证码并缓存验证码
    check_sms_code("login",185xxxx2333,$code);//校验验证码
~~~
- aes对称加密/解密
~~~
    aes_decrypt($decryptedString);
    aes_encrypt($array);
~~~
### Dcat速通 - 列表操作方法
~~~
$grid->quickSearch('order_no')->placeholder('搜索订单号'); //快速搜索框
$grid->model()->orderBy("id",'desc');//修改排序
$grid->disableFilterButton();	//禁用筛选条件
$grid->disableRefreshButton();	//禁用刷新按钮
$grid->disableRowSelector();	//取消全选

$grid->disableDeleteButton(); 	//禁用删除
$grid->disableViewButton(); 	//禁用详情按钮
$grid->disableEditButton(); 	//禁用编辑按钮
$grid->disableCreateButton(); 	//禁用新增

$grid->fixColumns(2);			//固定前两列与最后一列 ，页面过长时左右滚动

$grid->column('title')
    ->sortable()                //字段可以排序
    ->editable()                //允许快速编辑，和switch()都是走的表单保存，必须在form中有这个字段
    ->limit(20)                 //最多显示20个字符，超出省略号
$grid->column('image')->image(null,50,50); //图片，尺寸50*50
$grid->column('创建时间')->display(function()){ //自定义返回格式
    return substr($this->created_at,0,10);
})
$grid->column('status','订单状态')
    ->using([0=>'未支付',1=>'已支付'])
    ->badge(['default'=>'danger','1'=>'success'])       //加样式，也可用   dot
$grid->display();

$grid->export()->rows(function (array $rows) {
    foreach ($rows as $index => &$row) {
        $row['name'] = $row['first_name'].' '.$row['last_name'];
    }

    return $rows;
}); 

//数据导出
$grid->export()
    ->titles(['title'=>'文章标题','created_at'=>'发布时间'])    //自定义表头
    ->filename('租赁订单')  //自定义文件名
    ->rows(function (array $rows) {         //修改数据
        foreach ($rows as $index => &$row) {
            $row['name'] = $row['first_name'].' '.$row['last_name'];
        }
    
        return $rows;
    })  
//导入，相关文件：/app/Admin/Extensions/Excel/ImoportTool.php  /resources/views/admin/tool/import.blade.php
$grid->tools(new ImportTool('/user/import'));
~~~

### Dcat速通 - 表单常用操作方法
~~~
$form->text("name")
    ->rules("between:0,9999")   //自定义验证规格，
    ->required()                //必填
    ->help()                    //下方提示语
    ->readonly()                //只读
    ->disable()                 //禁用
    ->maxLength(100)            //最大长度，仅text可用
    
//选择框：select , radio , checkbox
$form->radio("status")
    ->default(1)            //默认值
    ->saveAsJson()          //保存为json字符串
    ->saving(function ($value) {
        // 转化逗号拼接字符串保存到数据库
        return implode(',',$value);
    });
    ->options([1=>'上架',0=>'下架‘)
    ->when([1],function(Form $form){
        //当选中1的时候显示
    });

//上传
$form->image('logo')
    ->disk('oss')          //指定文件驱动
    ->maxSize(1024)         //文件大小限制（KB）
    ->saveFullUrl()         //是否保存域名，只对默认上传接口生效，自定义url不行
    ->url('/upload')        //自定义上传接口
$form->file('file')         
    ->accept('jpg,png,gif,jpeg') //限制文件类型
// 限制最大上传数量
$form->multipleImage("banners")
    ->sortable();           //可进行排序
    ->limit(10);            //限制数量
    ->saving(function ($paths) {    //自定义保存格式
        // return implode(',', $paths); 
        return json_encode($paths);
    }); 

//地图选点
$form->map("latitude","longitude","门店位置");

//
$form->currency('price')->symbol('￥');

if($form->isCreating()){//表单是否是新增操作

}

if($form->isDeleting()){//表单是否是删除操作
    
}

$form->deleting(function(Form $form){//表单删除前
    $dataArr = $form->model()->toArray();   //这里是取到的数组
    foreach($dataArr as $item){
        if($item['status']>0){
            return $form->response()->error('订单已支付，无法删除');//中断删除
        }
    }
});
$form->saving(function(Form $form){//表单修改保存前
    if($form->model()->status<1){
    
    }
});
$form->saved(function(Form $form){//表单修改保存后
    if($form->model()->status==1){
        
    }
});
~~~

## 常见问题
### 1. composer安装依赖包失败？
将composer.json中的`minimum-stability`节点改为`dev`,然后再运行`composer update`。

### 2. 如何在不修改vendor目录的情况下修改后台界面、增加功能，
①. 将vendor/dcat/laravel-admin/resoures/views/目录复制到/resoures/views/dcat/

②. 在app/Admin/bootstrap.php中添加以下代码
~~~
   app('view')->prependNamespace('admin', resource_path('views/dcat'));
~~~
③. 在新的目录下尽情修改后台界面
### 3.和纯净版dcat_admin比，还做了哪些改动
1. 在admin/bootstrap.php中对列表和表单做了一些默认操作，例如关闭了'查看'按钮,这样开发过程中就不用管show方法，一般只需要处理grid和form即可
2. 默认集成了dcat的分布表单和操作日志插件