logo

插件开发指南 ​

概述 ​

InnoShop 的插件机制是一个功能强大的工具，它允许开发者以模块化的方式扩展商城系统的功能。利用 Laravel 框架的 ServiceProvider，插件可以轻松地注册到系统中，涵盖 MVC、数据库迁移(migrations)、路由(routes)、视图(views)、语言包(lang)、中间件(middleware)以及命令行脚本(console command)等。

插件原理 ​

InnoShop 插件基于 Laravel 的自动发现和引导机制，确保插件的各个组成部分能够被系统识别和加载。插件的 PHP 代码遵循 PSR-4 自动加载规范，即目录名和类名应采用 StudlyCaps（大驼峰命名法）。

插件目录结构 ​

一个典型的插件目录结构如下：

  • Controllers - 控制器目录，包含前后台控制器, 非必须。
  • Lang - 语言包目录，与 /resources/lang 目录结构一致, 非必须。
  • Middleware - 中间件目录，区分前台和后台中间件, 非必须。
  • Migrations - 数据库迁移目录, 非必须。
  • Models - 模型目录，定义数据表结构和关系, 非必须。
  • Repositories - 数据仓库目录，包含数据访问类, 非必须。
  • Routes - 路由目录，包含插件的自定义路由, 非必须。
  • Public - 静态文件目录，如图片等, 非必须。
  • Views - 插件模板目录，存放 Blade 模板文件, 非必须。
  • Boot.php - 插件启动类，包含 init 方法用于添加钩子, 非必须。
  • fields.php - 插件配置文件，定义插件配置字段, 非必须。
  • composer.json - 插件依赖的第三方 composer 包，非必须。
  • config.json - 插件基本信息文件，包含编码、名称、描述等, 必须。

注意：在 InnoShop 插件的目录结构中，Routes 目录需要包含特定命名的文件：panel.php 用于管理后台路由配置，以及 front.php 用于前端路由配置。

插件配置字段说明 ​

一个简单的 fields.php 如下所示

php
return [
    [
        'name'      => 'type',     // 字段名称
        'label'     => '类型'       // 与 label_key 二选一, label 表示字段显示名称
        'label_key' => 'common.type',  // 与 label 二选一, 'common.type' 将调用插件语言包定义的 key 来展示字段名称 
        'type'      => 'select',   // 字段类型, 具体可选类型将在下面章节讲解
        'options'   => [
            ['value' => 'fixed', 'label_key' => 'common.fixed'],
            ['value' => 'percent', 'label_key' => 'common.percent'],
        ],
        'required' => true,        // 是否必填项
        'rules'    => 'required',  // 字段验证规则, 参考 https://laravel.com/docs/11.x/validation#available-validation-rules
    ],
    [
        'name'      => 'value',
        'label_key' => 'common.value',
        'type'      => 'string',
        'required'  => true,
        'rules'     => 'required',
    ],
];

配置字段类型说明 ​

  • bool - 布尔类型，用于表示开关状态。
  • checkbox - 复选框，适用于多选项场景。
  • image - 图片上传，保存上传图片的路径。
  • multi-rich-text - 多语言富文本框，适用于多语言环境下的富文本编辑。
  • multi-string - 多语言字符串，适用于多语言环境下的简单文本编辑。
  • multi-textarea - 多语言多行文本框，适用于多语言环境下的多行文本输入。
  • rich-text - 富文本框，用于编辑格式化文本内容。
  • select - 下拉选项，提供选择单一选项的功能。
  • string - 字符串，用于输入和存储简短的文本信息。
  • textarea - 多行文本框，适用于长文本输入。

配置字段使用说明 ​

无论是在模型（Model）、视图（View）还是控制器（Controller）中，您都可以使用 plugin_setting('pluginName', 'configKey') 函数来获取插件的配置值

插件开发规范 ​

  1. 命名规范 - 遵循 StudlyCaps，确保自动加载无误。
  2. 目录结构 - 按照上述目录结构组织插件文件。
  3. 配置文件 - 使用 fields.php 和 config.json 定义插件配置。
  4. 模板引用 - 使用 plugin_asset 助手函数引用静态资源。
  5. 路由定义 - 在 Routes 目录下定义插件的路由。

插件开发流程 ​

以开发 友情链接(PartnerLink) 插件为例：

1. 创建插件目录 ​

  • 在 /plugins 目录下创建名为 PartnerLink 的目录，并创建必须的文件 config.json，定义插件的基本信息。示例如下,
php
{
    "code": "partner_link",
    "name": {
        "zh_cn": "友情链接",
        "en": "Partner Links"
    },
    "description": {
        "zh_cn": "友情链接",
        "en": "Partner Links"
    },
    "type": "feature",
    "version": "v1.0.0",
    "icon": "/image/logo.png",
    "author": {
        "name": "InnoShop",
        "email": "edward@innoshop.com"
    }
}

2. 编写代码 ​

  • 在插件根目录创建入口文件 Boot.php，并根据需要开发插件的控制器、模型、视图等。 Hook部分可以参考 Hook开发文档 入口文件代码如下所示,
php
namespace Plugin\PartnerLink;

use Plugin\PartnerLink\Models\PartnerLink;

class Boot
{
    /**
     * 初始化插件时执行的方法。
     */
    public function init(): void
    {
        /**
         * 修改后台管理界面左侧菜单，添加友情链接的菜单项。
         * 通过监听系统钩子，将友情链接菜单项添加到后台菜单数组中。
         */
        listen_hook_filter('component.sidebar.plugin.routes', function ($data) {
            // 添加友情链接菜单项
            $data[] = [
                'route' => 'partner_links.index',  // 指定路由地址
                'title' => '友情链接',  // 显示的菜单标题，支持多语言定义。 例如使用 trans('PartnerLink::common.title'), 语言资源包需要在 Lang 目录预先定义
            ];

            return $data;
        });

        /**
         * 在 Blade 模板的 footer 顶部插入友情链接的 HTML。
         * 使用 Blade 模板插入功能，在指定位置添加友情链接的展示。
         */
        listen_blade_insert('layouts.footer.top', function ($data) {
            // 获取启用的友情链接数据, Model 或者 可以按自己需求定义
            $data['links'] = PartnerLink::query()->where('active', 1)->limit(10)->get();

            // 返回渲染后的友情链接视图
            return view('PartnerLink::front.partner_links', $data);
        });
    }
}
  • 在 Migrations、Routes、Controllers、Models、Views 目录下分别定义对应的代码。

3. 配置文件 ​

  • 如果需要配置，则需要定义 fields.php。

插件启用与禁用 ​

  • 插件的启用和禁用通过 InnoShop 的后台管理系统进行。

结语 ​

InnoShop 的插件机制为开发者提供了一个灵活、扩展性强的平台。通过本指南，开发者可以快速掌握插件开发的基本流程和规范，为 InnoShop 贡献丰富的功能扩展。