整合插件

适配后台暗色模式插件

整合普通插件

在使用其它插件的方法、模型、代码之前，需按以下方法进行判断

//读取插件的状态，epay为插件标识
$info = get_addon_info('epay');
if($info && $info['state']){
    //代码逻辑
} else {
    exception("请确保微信支付宝整合插件已安装并启用");
}

如果需要判断依赖插件的版本可使用

//读取插件的状态，epay为插件标识
$info = get_addon_info('epay');
if($info && $info['state']){
    if(version_compare($info['version'], '1.3.0') >= 0){
        //代码逻辑
    } else {
        exception("请安装微信支付宝整合插件1.3.0及以上版本");
    }
} else {
    exception("请确保微信支付宝整合插件已安装并启用");
}

如需读取插件配置可使用

//读取插件的配置，epay为插件标识
$config = get_addon_config('epay');
$version = $config['version'] ?? 'v2';

整合支付插件

默认微信支付宝整合插件是使用微信支付V2的API接口，如需使用V3的接口需要做特殊处理。
目前微信支付宝整合插件已经发布1.3.0，从1.3.0开始支持微信支付V3的API接口，我们在整合微信支付宝插件时如果需要使用V3的接口，需要按以下的步骤进行操作。

准备工作

1、首先确保已经安装微信支付宝整合插件1.3.0+
2、在我们控制器代码的__construct或_initialize方法中使用set_addon_config('epay', ['version' => 'v3'], false);切换V3接口，该代码务必在__construct或_initialize方法中使用。
3、参照easyPay文档使用V3的接口：https://pay.yansongda.cn/docs/v3/quick-start/init.html

常用方法

//获取当前接口版本
\addons\epay\library\Service::getSdkVersion();

//判断当前是V2还是V3接口
\addons\epay\library\Service::isVersionV2();
\addons\epay\library\Service::isVersionV3();

插件内还提供了快捷获取微信支付宝插件配置和提交订单的方法(可选)，也可以参考easyPay的文档自行实例化使用。

/**
 * 获取初始化配置，V2和V3返回的结构不一致
 * @param string $type   支付类型
 * @param array  $custom 自定义微信支付宝相关配置，用于覆盖插件默认配置
 * @return array
 */
\addons\epay\library\Service::getConfig($type = 'wechat', $custom = []);

/**
 * 回调处理，V2和V3返回的对象不一致
 * @param string $type   支付类型
 * @param array  $custom 自定义微信支付宝相关配置，用于覆盖插件默认配置
 * @return array
 */
\addons\epay\library\Service::checkNotify($type = 'wechat', $custom = []);

/**
 * 提交订单
 * @param array|float $amount    订单金额
 * @param string      $orderid   订单号
 * @param string      $type      支付类型,可选alipay或wechat
 * @param string      $title     订单标题
 * @param string      $notifyurl 通知回调URL
 * @param string      $returnurl 跳转返回URL
 * @param string      $method    支付方法，支持web/wap/app/scan/pos/mp/miniapp
 * @param string      $openid    Openid
 * @param array       $custom    自定义微信支付宝相关配置，用于覆盖插件默认配置
 * @return Response|RedirectResponse|Collection
 */
\addons\epay\library\Service::submitOrder($amount, $orderid = null, $type = null, $title = null, $notifyurl = null, $returnurl = null, $method = null, $openid = '', $custom = []);

//自定义微信参数参考示例
$paytype = 'wechat';
$config = get_addon_config('example');
if ($paytype == 'wechat') {
    //优化使用插件中配置的appid
    $app_id = empty($config['app_id']) ? '' : $config['app_id'];
    $official_appid = empty($config['official_appid']) ? '' : $config['official_appid'];
    $miniapp_id = empty($config['wx_appid']) ? '' : $config['wx_appid'];
    $custom = \addons\epay\library\Service::isVersionV3() ? [
        'app_id'      => $app_id, //APP
        'mp_app_id'   => $official_appid,//公众号
        'mini_app_id' => $miniapp_id,//小程序
    ] : [
        'appid'      => $app_id, //APP
        'app_id'     => $official_appid, //公众号
        'miniapp_id' => $miniapp_id, //小程序
    ];
    $custom = array_filter($custom);
    
    //获取配置
    $config = \addons\epay\library\Service::getConfig($paytype, $custom);

    //发起支付
    $response = \addons\epay\library\Service::submitOrder($amount, $orderid, $type, $title, $notifyurl, $returnurl, $method, $openid, $custom);
    
    //回调检测
    $pay = \addons\epay\library\Service::checkNotify($paytype, $custom);
}

温馨提示：
1、你的支付参数配置信息可以在自己的应用中进行定义和配置
2、V2和V3的接口中特别是微信支付差异比较大，需特别注意。
3、custom自定义键名支持所有epay插件中微信和支付宝的相关配置

整合云存储上传插件

在插件开发中可以快速的整合FastAdmin插件市场的云存储上传插件。如果是后台CRUD自动生成的上传按钮无需任何特殊配置。

前端文件流上传

如果我们FastAdmin框架中的前端页面需要通过JS将文件流上传至云存储或服务器，此时我们可以通过FastAdmin框架自带的方法进行上传，代码如下：

require(['upload'], function(Upload){
    //file为文件流
    Upload.api.send(file, function(data, ret, msg){
        //成功的回调
        var url = data.url; //相对URL
        var fullurl = data.fullurl; //完整URL
    }, function(data, ret, msg){
        //失败的回调
    });
});

后端文件流上传

如果我们的后端需要将服务器的文件上传至云存储或服务器，此时我们可以通过以下方式来实现。首先我们需要建议一个File类，存储位置位于addons/mydemo/library目录下，类代码如下：

<?php

namespace addons\mydemo\library;

/**
 * 文件类
 */
class File extends \think\File implements \ArrayAccess
{

    public function __construct($filename, $mode = 'r')
    {
        parent::__construct($filename, $mode);
    }

    public function offsetExists($offset): bool
    {
        return isset($this->info[$offset]);
    }

    #[ReturnTypeWillChange]
    public function offsetGet($offset)
    {
        return $this->info[$offset];
    }

    public function offsetSet($offset, $value): void
    {
        $this->info[$offset] = $value;
    }

    public function offsetUnset($offset): void
    {
        unset($this->info[$offset]);
    }
}

然后调用下面的代码进行上传文件：

// 上传成功后该文件将被删除，请务必使用临时文件，这里$tempFile为你服务器准备上传的文件
$tempFile = ROOT_PATH . 'runtime' . DS . 'mydemo' . DS . 'tempfile.png';

// 这里的 File 类必须使用我们自定义的 \addons\mydemo\library\File 类，不能使用 \think\File 类
$file = new \addons\mydemo\library\File($tempFile);
$file->setUploadInfo(['name' => basename($tempFile), 'type' => $file->getMime(), 'tmp_name' => $tempFile, 'error' => 0, 'size' => $file->getSize()]);
$file->isTest(true);

$this->request->file(['file' => $file]);

$storage = config('upload.storage');
if ($storage === 'local') {
    // 本地上传
    $upload = new \app\common\library\Upload($file);
    $attachment = $upload->upload();
    return json(['code' => 1, 'message' => '上传成功', 'data' => ['url' => $attachment->url, 'fullurl' => cdnurl($attachment->url, true)]]);
} else {
    
    // 添加允许上传的行为
    \think\Hook::add('upload_config_checklogin', function () {
        return true;
    });
                
    // 云存储上传
    request()->param('isApi', true);
    try {
        \think\App::invokeMethod(["\\addons\\{$storage}\\controller\\Index", "upload"], ['isApi' => true]);
        // 这里无法获取上传返回的数据，请在下方的 HttpResponseException 中处理
    } catch (\think\exception\HttpResponseException $e) {
        $ret = $e->getResponse()->getData();
        return json($ret);
    }
    return;
}

如果我们需要使用API上传文件至云存储，有以下两种方式可以使用：

框架自带API上传(需登录)

在使用框架自带的API进行上传文件，则要求传递用户当前的token，如果应用插件未使用FastAdmin的默认用户体系，可能无法获取到用户的token，此时建议使用插件自定义API上传的形式

请求地址

http://www.yoursite.com/api/common/upload

请求方法

POST

请求参数

自定义API上传(无需登录或自行鉴权)

如果我们的应用插件未使用FastAdmin的默认用户体系，可能无法获取到用户的token，从而无法使用框架自带的API上传接口，此时我们可以采用自定义API进行上传。

请求地址(自定义)

http://www.yoursite.com/addons/demo/common/upload

请求方法

POST

请求参数

代码示例

namespace addons\demo\controller;

use app\common\exception\UploadException;
use app\common\library\Upload;
use think\addons\Controller;
use Exception;
use think\App;
use think\Config;
use think\Hook;
use think\Lang;

class Common extends Controller 
{
    //上传方法
    public function upload()
    {
        // 自定义鉴权判断
        // 强烈建议这里判断$file = $this->request->file('file');的后缀和mimetype

        // 载入语言包，避免出现英文错误提示
        Lang::load(APP_PATH . 'api/lang/zh-cn.php');
        
        // 获取上传配置
        $uploadConfig = Config::get("upload");

        // 兼容云存储上传
        if ($uploadConfig['storage'] != 'local') {
            // 这里可以修改允许上传文件的后缀或修改存储的文件路径，例如只允许上传图片
            set_addon_config($uploadConfig['storage'], ['savekey' => '/uploads/{year}{mon}{day}/{filemd5}{.suffix}', 'mimetype' => 'jpg,png,bmp,jpeg,gif'], false);

            // 添加允许上传的行为
            Hook::add('upload_config_checklogin', function () {
                return true;
            });

            request()->param('isApi', true);
            App::invokeMethod(["\\addons\\{$uploadConfig["storage"]}\\controller\\Index", "upload"], ['isApi' => true]);
        } else {
            // 这里可以修改允许上传文件的后缀或修改存储的文件路径，例如只允许上传图片
            //Config::set('upload', array_merge($uploadConfig, ['savekey' => '/uploads/{year}{mon}{day}/{filemd5}{.suffix}', 'mimetype' => 'jpg,png,bmp,jpeg,gif']));

            $attachment = null;
            // 默认普通上传文件
            $file = $this->request->file('file');
            try {
                $upload = new Upload($file);
                $attachment = $upload->upload();
            } catch (UploadException $e) {
                $this->error($e->getMessage());
            }
            return json(['code'=>1, 'msg'=>'上传成功', 'data'=>['url' => $attachment->url, 'fullurl' => cdnurl($attachment->url, true)]]);
        }
    }
}

整合短信发送插件

如需整合插件市场中的短信插件，请参考application/api/common/controller/Sms.php中的代码

整合第三方登录插件

如果使用了FastAdmin自带的fa_user表，建议整合第三方登录插件，第三方登录插件支持微信、微博、QQ，支持微信扫码登录，支持UnionID机制。

当我们开发的应用插件获取到了第三方平台的openid以后，可以调用\addons\third\library\Service::connect来创建关联，如下：

/**
     * 绑定第三方登录
     * @param string $platform 平台，wechat=微信,qq=QQ,weibo=微博
     * @param array  $params   参数，必须包含openid
     * @param array  $extend   会员扩展信息，可使用fa_user表中的字段
     * @param int    $keeptime 有效时长，默认为永久
     * @return boolean
     */
\addons\third\library\Service::connect('wechat', [
    'openid'=>'用户的openid',
    'unionid'=>'用户的unionid', //仅在微信
    'apptype'=>'第三方类型',//miniapp=微信小程序,mp=公众号,web=PC,app=APP
    'nickname'=>'用户昵称',//可以为空
    'avatar'=>'头像',//可以为空
], [
    'mobile'=>'手机号', //可选，可使用fa_user表字段
    'username'=>'用户名' ,//可选，可使用fa_user表字段
]);

如果需要判断用户是否绑定第三方登录，可以使用如下判断：

/**
     * 判断是否绑定第三方
     * @param string $platform 平台
     * @param string $openid   Openid
     * @param string $apptype  平台类型(web/miniapp/mp/app)，可选
     * @param string $unionid  Unionid，可选
     * @return bool
     */
$isBind = \addons\third\library\Service::isBindThird('wechat', '用户的openid','miniapp','用户的unionid');