diff --git a/docs/guide/安装.md b/docs/guide/安装.md index 66ce0b4a..63f96036 100644 --- a/docs/guide/安装.md +++ b/docs/guide/安装.md @@ -2,9 +2,30 @@ > 这篇为炸毛框架以及环境的部署教程。 -## 主机手动部署环境 +框架部署分为环境部署和框架部署。框架部署非常简单，只需要通用的指令，下方主要说环境部署。 -### Ubuntu / Debian / Kali +## Docker 部署 PHP 环境 +如果你不想干扰主机的环境，可以使用 Docker 进行拉取框架适用的 PHP7 with Swoole Extension Docker Container。本框架安装教程中使用的 DockerHub 及 Dockerfile 构建文件所构建的容器均为独立的容器，和框架无关，此 Docker 也可以用作运行**其他基于 php-cli 模式的项目**。 + +方法一、直接拉取远程容器（推荐） +```bash +docker pull zmbot/swoole +``` + +方法二、从 Dockerfile 构建容器 +```bash +git clone https://github.com/zhamao-robot/zhamao-swoole-docker.git +cd zhamao-swoole-docker/ +docker build -t zm . +``` + +!!! note "从 Dockerfile 构建容器的提示" + + 使用 Dockerfile 构建后，需要将下方所有的 `zmbot/swoole` 全部更换成 `zm`，或者你上方指令中的 `-t` 参数后方的名称，具体可以详情查阅 Docker 的文档。 + +## 主机部署 PHP 环境 + +### Debian 系列（Ubuntu、Kali ） 需要的系统内软件包为：`php php-dev php-mbstring gcc make openssl php-mbstring php-json php-curl php-mysql wget composer` @@ -29,55 +50,50 @@ brew install php composer pecl install swoole ``` -## 手动部署框架 +### 其他 Linux 发行版 + +其他 Linux 发行版，如 CentOS，Fedora，Arch 等暂时还没有经过严格的测试需要哪些依赖，大体和 Ubuntu、Debian 系需要的依赖包差不多，可根据安装过程中报错提示依次安装，或者直接使用 Docker 环境。 + +## 安装框架 + +恭喜你，前方通过 Docker 或主机安装环境后可以开始构建框架的开发脚手架了！ + +如果你是通过**主机安装 PHP 部署的环境**，下方是通过脚手架来构建项目的命令行。 ```bash -# 方法1: 从 composer 模板项目快速新建（前提是主机有安装 composer） -composer create-project zhamao/framework-starter 你的项目名称 -# 方法2: 从 composer 引入项目（前提是主机有安装 composer） -mkdir 你的项目名称 && cd 你的项目名称 -composer require zhamao/framework -vendor/bin/start init -``` - -## Docker 部署环境和框架 - -对于不想部署到主机环境的情况，推荐直接使用 Docker。 - -!!! Note "提示" - - 本框架内安装的 Docker 容器包括框架本身和开发者开发的模块代码等，此镜像也可用于其他 Swoole 框架的启动，框架本身是需要从 GitHub 拉取或 composer 拉取的。 - -### Docker 容器拉取和构建 - -```bash -# 自行构建 Swoole 环境容器 -git clone https://github.com/zhamao-robot/zhamao-swoole-docker.git -cd zhamao-swoole-docker/ -docker build -t zm . -# 或者使用 dockerhub 构建好的镜像构建 Swoole 环境容器 -docker pull zmbot/swoole -``` - -### 使用 Docker 容器初始化 composer 和框架代码 - -```bash -# 使用 GitHub 克隆快速开始项目仓库 git clone https://github.com/zhamao-robot/zhamao-framework-starter.git -cd zhamao-framework-starter -docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zm composer update -# 如果使用 dockerhub 拉取的，把 `zm` 换成 `zmbot/swoole` 即可 +cd zhamao-framework-starter/ +composer update ``` +如果是通过 **Docker 部署的环境**，则需要在先克隆脚手架后在文件夹内使用 Docker 命令下的 `composer update`。 + +```bash +git clone https://github.com/zhamao-robot/zhamao-framework-starter.git +cd zhamao-framework-starter/ +docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zmbot/swoole composer update +``` + +或者在 Docker 环境下，你可以直接使用如下方法拉取和快速启动一个最标准的框架。 + +```bash +git clone https://github.com/zhamao-robot/zhamao-framework-starter.git +cd zhamao-framework-starter +./run-docker.sh # 在正式版炸毛框架 v2 发布后可用，测试版暂不放出 +``` + + ## 启动框架 - +本地环境启动方式： ```bash -# 本地环境拉取 zhamao-framework-starter 后启动方式 cd zhamao-framework-starter vendor/bin/start server +``` -# 使用 Docker 启动 -docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zm vendor/bin/start server # 如果使用 dockerhub 拉取的，把 `zm` 换成 `zmbot/swoole` 即可 +使用 Docker 启动： +```bash +cd zhamao-framework-starter +docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zmbot/swoole vendor/bin/start server ``` 启动后你会看到和下方类似的初始化内容，表明启动成功了 @@ -106,6 +122,13 @@ working_dir: /Users/jerry/project/git-project/zhamao-framework 单纯运行 炸毛框架 后，如果不部署或安装启动任何机器人客户端的话，仅仅相当于启动了一个 监听 20001 端口的WebSoket + HTTP 服务器。你可以通过浏览器访问：http://127.0.0.1:20001 ，或者你部署到了服务器后需要输入服务器地址。 +!!! note "安装和部署总结" + + 根据上方描述，此文档中剩余提到的所有 Bash 命令，如果使用 Docker 部署环境，则需要加上 Docker 环境的指令：`docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zmbot/swoole`，如执行其他 Linux 指令（以查看 PHP 版本为例）：`docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zmbot/swoole php -v`。 + ## 使用 IDE 等工具开发代码 -我们使用文本编辑器进行炸毛框架开发，在使用集成开发环境 **IDEA** 或 **PhpStorm** 时，推荐通过插件市场搜索并安装 **PHP Annotations** 插件以提供注解命名空间自动补全、注解属性代码提醒、注解类跳转等，非常有助于提升开发效率的功能。 \ No newline at end of file +我们使用文本编辑器进行炸毛框架开发，在使用集成开发环境 **IDEA** 或 **PhpStorm** 时，推荐通过插件市场搜索并安装 **PHP Annotations** 插件以提供注解命名空间自动补全、注解属性代码提醒、注解类跳转等，非常有助于提升开发效率的功能。 + +## 进阶环境部署和开发 +炸毛框架还支持更多种启动方式，如源码模式、守护进程模式，具体后续有关环境和部署的进阶教程，请查看 [进阶开发](/advanced/) 部分！ \ No newline at end of file diff --git a/docs/guide/快速上手-机器人.md b/docs/guide/快速上手-机器人.md index 9a5674c4..f94df246 100644 --- a/docs/guide/快速上手-机器人.md +++ b/docs/guide/快速上手-机器人.md @@ -12,7 +12,9 @@ ## 机器人客户端 -机器人客户端是炸毛框架以外的程序或软件，目前炸毛框架支持的机器人客户端通信标准为 OneBot 标准，只要你的机器人客户端是 OneBot 标准的，就可以和炸毛框架进行无缝对接。 +开发之前请注意，**机器人客户端和框架相互独立！**故有关**机器人客户端**出现的问题请到对应机器人客户端开发者或 GitHub 项目中咨询和讨论，炸毛框架为对接机器人客户端的一个快速开发的框架。 + +机器人客户端是炸毛框架以外的程序或软件，目前炸毛框架支持的机器人客户端通信标准为 OneBot 标准（原 CQHTTP），只要你的机器人客户端是 OneBot 标准的，就可以和炸毛框架进行无缝对接。 OneBot 机器人部分的选择详情见 [OneBot 实例](/guide/OneBot实例/)。 @@ -214,7 +216,7 @@ OneBot 机器人部分的选择详情见 [OneBot 实例](/guide/OneBot实例/) * @CQCommand("echo") */ public function repeat() { - $repeat = ctx()->getArgs(ZM_MATCH_ALL, "请输入你要回复的内容"); + $repeat = ctx()->getFullArg("请输入你要回复的内容"); ctx()->reply($repeat); //return $repeat; // 这样的效果等同于 ctx()->reply() } diff --git a/docs/guide/编写模块.md b/docs/guide/编写模块.md new file mode 100644 index 00000000..0d2453af --- /dev/null +++ b/docs/guide/编写模块.md @@ -0,0 +1,80 @@ +# 编写模块 + +到现在为止，我们还在使用框架的默认模块 `Example/Hello.php`，在开始编写自己的模块应用之前，我们先说明一些编写代码的约定。 + +## 加载模块 + +框架默认使用脚手架构建好后，目录结构大致为下面这样： + +```bash +zhamao-framework-starter/ +├── config/ # 项目的配置文件文件夹，如 global.php +├── src/ # 项目的主要源码目录 +│ ├── Module/ # 用户编写的模块目录 +│ │ └── Example/ # 模块文件夹名称 +│ │ └── Hello.php # 模块内的类 +│ └── Custom/ # 用户自定义的全局方法、全局注解类等存放的目录 +├── vendor/ # Composer 依赖加载目录 +└── composer.json # Composer 配置文件 +``` + +其中我们脚手架包含的默认模块 `Example` 下的 `Hello` 类，就是用户写模块的位置。你也可以根据实际情况，自行添加更多的模块文件夹甚至单文件模块。 + +需要注意的是，所有文件夹名称和 `.php` 文件必须遵循 [psr-4 规范](https://learnku.com/docs/psr/psr-4-autoloader/1608)，简单来说，`src/` 目录下的文件夹，子文件夹要写成命名空间，比如默认框架中 `Example/` 下的 `.php` 文件的命名空间为 `namespace Module\Example;`，且一个 `.php` 文件推荐只包含一个 `class`、`trait` 或 `interface`。 + +```php +; +class ModuleA {} +``` + +!!! fail "警告" + 如果没有遵守上方的类和文件命名规则的话（文件名、文件夹名和命名空间的统一性），在加载框架时就会报错，无法找到对应的类。因为框架的注解解析依赖于 Composer 中 psr-4 规则的自动加载。 + +## 创建模块 +### 标准形式 +我们这里以 `Entertain` 娱乐模块的创建为例，新建一个内有 `Dice.php` 掷骰子功能的模块，目录结构如下，在 `Module/` 下新建文件夹 `Entertain/`，再在此子目录下新建 `Dice.php` 文件。 +```bash +zhamao-framework-starter/ +└── src/ + └── Module/ + └── Entertain/ + └── Dice.php +``` +新建的 PHP 文件按照如下方式编写： +```php + 机器人客户端 -> 连接客户端的框架（炸毛框架） +- 框架处理逻辑后返回给用户的消息 -> 机器人客户端 -> QQ用户 + +第一步，我们以框架这边的角度考虑，我们称之为“事件”，我们编写代码所做的就是要响应这一事件。 + +TODO：写到这里了。 \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index c44b981a..6e29bef8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,6 +57,7 @@ nav: - 快速上手（HTTP篇）: guide/快速上手-http.md - 选择聊天机器人实例: guide/OneBot实例.md - 基本配置: guide/基本配置.md + - 编写模块: guide/编写模块.md - 事件和注解: - 事件和注解: event/index.md - 框架组件: