一、插件目录结构说明

QStack所有插件都是存储在项目根目录qstack下的addons目录，一个插件一个目录，目录名必须和插件标识相同。

demo_addon //插件标识(示例插件),全小写，单词以下划线分割，尽量使用专有名词，以避免冲突。
| —- root //存放源代码目录
| —- config.html //插件配置项
| —- config.php //插件配置项属性
| —- db_schema.json //数据库配置
| —-DemoAddon.php // 插件安装与卸载
| —- info.ini //插件信息配置

• root 存放插件源代码的目录，存储对应原项目中qstack下的目录以及文件

  

• config.html 插件配置时使用的视图模板（非必须），当存在时，插件管理中点配置按钮会调用这个视图文件，配置文件示例：

  <ul>
    <li>
        <span>Arg1</span>
        <div class="qg-text-item">
            <input type="text" name="arg1" value="{$config.arg1}">
        </div>
    </li>
  </ul>
  

  

• config.php 插件的配置文件（非必须），当存在时，我们在后台插件管理中点配置按钮时会保存在此文件，配置文件示例：

<?php
    return array (
  'ad_monitor_validity' => '30',
);

• db_schema.json 插件需要执行的数据库SQL语句脚本，配置文件示例：

  {
   "demo_addon": {
       "tableName": "demo_addon",
       "columns": {
           "id": {
               "name": "id",
               "dataType": "int",
               "type": "int(11)",
               "columnDefault": null,
               "isNullable": false,
               "autoIncrement": true
           },
           "value_old": {
               "name": "value_old",
               "dataType": "varchar",
               "type": "varchar(255)",
               "columnDefault": null,
               "isNullable": true,
               "autoIncrement": false
           },
           "value": {
               "name": "value",
               "dataType": "int",
               "type": "int(11)",
               "columnDefault": null,
               "isNullable": true,
               "autoIncrement": false
           }
       },
       "primaryKeys": [
           "id"
       ],
       "uniqueIndexs": []
   }
  }
  

• DemoAddon.php 插件安装与卸载，配置文件示例：

  该类至少需要实现 install（插件安装） uninstall（插件卸载） 这两个方法， upgrade（插件升级）的方法可根据自己的特殊情况进行处理

 <?php
namespace demo_addon;

use app\common\contracts\addon\ConfigureValidator;
use Exception;
use think\facade\Db;

class DemoAddon implements ConfigureValidator
{
    // 插件安装 v1版本
    public function install($current_version = null)
    {
        Db::name('demo_addon')->insertAll([
            ['value' => 1, 'value_old' => 'demo_addon_database_value-1'],
            ['value' => 2, 'value_old' => 'demo_addon_database_value-2']
        ]);

        $this->install_v3($current_version);
    }

    // 插件卸载
    public function uninstall()
    {
        Db::execute('drop table demo_addon');
    }

    // 插件配置项验证
    public function configureValidate(array $configure)
    {
        if (!$configure['arg1']) {
            throw new Exception("请填写 arg1");
        }
    }

    // 插件升级
    public function upgrade()
    {
       //do something;
    }
}

• info.ini 插件基础信息配置，配置文件示例：

name = demo_addon #插件标识
title = 示例插件 #插件名称
intro = 示例插件 #插件描述
author = xxx    #插件作者
version = 1.1 #插件版本

二、插件集成方式

• 独立插件

  这种类型的插件可以不需要依赖于系统其它部分模块而独立存在，可直接将源代码如demo_addons目录下的代码拷贝到项目根目录qstack下的addons目录，插件被安装时，demo_addons/root 目录中的文件会被逐一被拷贝并替换项目qstack目录中对应的文件，如前面demo_addon这个插件就是这种集成的方式。

• 钩子插件

  这种类型的插件需要依赖于原系统的模块而存在，如广告监控的钩子，现在需要在原系统用户注册的时候插入对应的访客记录，原系统已存在钩子VisitorToUserHook，该接口有个hookVisitorToUser方法，用户只需要在所定义的插件类AdMonitor实现这个方法，系统在用户注册这个环节会自动调用这个钩子的方法，实现用户所需要的功能。新增支付方式、短信通道、邮件通道皆可采用此方式。

 <?php
namespace ad_monitor;

use app\common\contracts\addon\ConfigureValidator;
use Exception;
use think\facade\Db;

// 广告监控插件类
class AdMonitor implements ConfigureValidator,VisitorToUserHook
{
    // 插件安装
    public function install($current_version = null)
    {
     //do something;
    }

    // 插件卸载
    public function uninstall()
    {
     //do something;
    }

    // 插件配置项验证
    public function configureValidate(array $configure)
    {
     //do something;
    }

    // 插件升级
    public function upgrade()
    {
       //do something;
    }

     // 注册用户增加访客记录
    public function hookVisitorToUser(int $userId)
    {
        AdMonitorModel::conversionUser($userId);
    }
}

三、插件调用

你可以在你需要调用插件钩子的地方执行execHook，如广告监控插件，在注册控制器RegisterController.class.php文件中埋入对应的钩子

class RegisterController extends HomeController
{
    private $userSession;

    public function _initialize()

      public function doRegister()
      {
      // do someing
          if($result){ // 注册成功
            Addon::execHook(VisitorToUser::class, (int)$flg['result']); //调用钩子，传入对应的参数，系统会自动调用插件实现的方法
          }
      }
}

四、 插件注意事项

• 插件入口类实现 app\common\contracts\addon\ConfigureValidator 接口，configureValidate 方法通过抛出异常来返回校验后的错误信息。
• 在插件根目录的 config.html 文件中进行页面表单参数的配置，该文件会被嵌入到统一的插件配置页面中，由统一的配置页面进行界面渲染，配置页面入口位于后台插件管理页面。
• 插件配置参数会被保存到插件根目录下的 config.php 文件中，插件可以通过 app\facade\Addon::getConfig()方法 获取插件的配置参数，插件标识作为参数传入。
• 对于数据库表结构的操作，需要生成数据库执行文件 db_schame.json，该文件可由脚本自动生成。例如，某个插件需要新增一张表 demo_table，在本地数据库中创建好该表的结构后，在项目根目录qstack下，执行 php think addon:db-schema demo_table > db_schema.json 即可生成该表的执行文件，当有多张表时，可在 demo_table 之后追加额外的表名，以空格分隔即可。系统会自动检测数据库的结构差异，自动进行更改。
• 对于数据库增删改查数据方面的操作，比如插件需要新增加、删除一个菜单，可以在插件主类AdMonitor中的install、upgrade方法做相应的数据插入、删除处理。