zhamao-framework/docs/plugins/develop.md

# 插件开发

在框架环境准备就绪后，可以使用框架提供的命令、工具集进行插件的开发。

如果你还没有阅读 [快速上手-聊天机器人](/guide/get-started.md) 章节的内容，请先阅读。

## 创建插件

框架默认支持两种形式的插件，一种是 `file` 单文件模式，另一种是 `psr4` 多文件模式。一般情况下，写一个较为简单的功能插件，推荐使用单文件模式，便于管理。
编写功能较多、需要分多个文件写逻辑的插件，推荐使用 `psr4` 多文件模式。

框架的插件命名方式基于 Composer，Composer 要求组件、插件的名称要有开发者名称和项目名称两部分组成。
例如，我的开发者代号仓库是 `jackson`，插件名称是 `group-manager`，最终你的插件名称就是 `jackson/group-manager`。

```bash
# 使用终端问答向导创建插件，可根据终端的提示选择你要创建插件的名称、类型和命名空间等内容。
./zhamao plugin:make --type=file
# 使用 file 类型的示例骨架创建插件，插件名称为 foobar/test-plugin
./zhamao plugin:make --type=file foobar/test-plugin
# 使用 psr4 类型的示例骨架创建插件，插件名称为 foobar/psr4-plugin，命名空间为 foobar
./zhamao plugin:make --type=psr4 --namespace=foobar foobar/psr4-plugin
# 设置插件作者名称、描述信息
./zhamao plugin:make --author=tom --description="示例插件"
```

### 单文件模式

单文件模式的优势在于以下几点：

- 代码较少的情况下，逻辑表达更清晰，可直接在单文件结构下编写机器人、HTTP 服务器的逻辑。
- 可以添加额外的框架事件 `onPluginLoad`（框架在读取插件元信息后触发的事件）。
- 可以添加额外的框架事件 `onPack`（插件在被打包时执行的回调函数）。

单文件模式下的插件目录结构如下图所示：

```text
plugins/
└── test-app/
    ├── main.php         # 你的插件源代码文件
    └── composer.json    # 插件元信息（如名称、版本等）
```

使用 file 模式创建的插件会在 `./plugins/` 目录下新建一个文件夹，文件夹名称一般为插件名称 `xxx/yyy` 的 `yyy`。如果遇到重名文件夹时，框架会提示重名。

当然，单文件模式也有劣势：

- 插件依赖了其他外部 Composer 组件时，依赖管理不方便。
- 插件逻辑较为复杂时，写到一个文件内会导致代码过长，不利于维护。
- 一些注解的绑定、中间件，均无法在单文件模式中使用。

### 多文件模式

多文件模式适用于几乎任何情况，有以下优势：

- 逻辑复杂时，使用 Class 类名和注解绑定的形式，有助于编写大型项目。
- 逻辑简单但功能点繁多时，可以使用类成员的多个绑定注解的方法区分功能逻辑，避免单文件的混乱。
- 可以使用注解的全部特性，例如中间件绑定、依赖注入等。

多文件模式下的插件目录结构如下图所示：

```text
plugins/
└── psr4-plugin/
    ├── composer.json       # 插件元信息（如名称、版本等）    
    ├── vendor/             # Composer 生成的插件依赖库目录和自动加载文件等   
    └── src/                # 你的插件源代码文件目录，符合 PSR-4 格式的
        ├── Psr4Plugin.php  # 使用创建插件命令生成的初始插件逻辑
        └── ...             # 如果你的插件想要分成多个 PHP 文件，那么这里可以有多个
```

### 混合模式

混合模式为单文件模式和多文件模式的结合，框架不提供创建混合模式插件脚手架的命令，但你可以自行混合。

混合模式其实就是多文件模式，只不过同时也可以引入一个单文件插件，弥补多文件模式没办法绑定 `onPack` 和 `onPluginLoad` 事件的问题。

混合模式在多文件模式的基础上多了一个 `main.php` 的单文件：

```text
plugins/
└── psr4-plugin/
    ├── composer.json       # 插件元信息（如名称、版本等）    
    ├── vendor/             # Composer 生成的插件依赖库目录和自动加载文件等   
    ├── main.php            # 插件逻辑（单文件部分）
    └── src/                # 你的插件源代码文件目录（多文件部分）
        ├── Psr4Plugin.php  # 使用创建插件命令生成的初始插件逻辑
        └── ...             # 如果你的插件想要分成多个 PHP 文件，那么这里可以有多个
```

在通过以上三种方式创建插件后，你可以通过 IDE、记事本等形式开始编写你的插件逻辑啦！

## 编写插件（WIP）

> 此处文档正在努力编写中！

插件的编写内容当然取决于异想天开的你，这里用最基本和最典型的例子来说明如何从零编写一个自己的插件。

### 机器人命令问答

在使用框架的上方创建插件命令创建了一个插件目录和骨架文件后，打开文件可以看到默认生成了一个 BotCommand 机器人聊天命令事件，返回的内容为一句简单的话。
你可以在创建插件后直接使用此命令，在对接机器人实现端（OneBot 12 实现）后，在与机器人对话的窗口或 App 内发送指令，即可测试机器人插件是否正常运行。

我们这里假设通过 psr4 模式创建了插件 `foobar/demo2`，初始化时预置的机器人聊天命令代码可能是下面这样：

```php
#[BotCommand(match: '测试demo2')]
public function firstBotCommand(BotContext $ctx): void
{
    $ctx->reply('这是foobar/demo2插件的第一个命令！');
}
```

<chat-box :my-chats="[
{type:0,content:'测试demo2'},
{type:1,content:'这是foobar/demo2插件的第一个命令！'},
]" />

在编写插件逻辑时，你可以自由使用框架内的各个组件和注解，这里不再过多描述。

## 插件打包

在写了在写了。

## 插件发布

在写了！