Flarum 社区插件开发 – 生成空白插件(一)

共码了3918个字
文内使用到的标签:

前言

不久前 HamCQ 社区被阮一峰老师收录在 239 期周刊 中,迅速带来了明显的流量高峰,站内迎来了社会各届人士,其中也存在着业余无线电爱好者及同行开发人员,收到了非常多的好友添加咨询,下班后,这篇文章便浮现在脑海中。

一个人的精力实在太有限。

社区基于 Flarum 上线运行两个月以来,我通过几次迭代,尝试开发了几款插件,拓展了更具有业余无线电爱好者风味的一些功能,意识到了他的强大性,现在对此框架插件开发机制及流程都有一定的了解,同时考虑到国内对此开发资料较少的情况,准备及时输出文档,让更多人可以参与进来,实现更多更有趣的功能,本文及系列文档同时会投递到 FlarumCN 社区。

本人主做后端 Go 开发,其它方面略有涉猎,接下来,我会尽可能详细的做一些流程介绍,如有不妥或遗漏之处,还请指教。

首先

假设你对 PHP 语言已经有一定的了解,尝试使用过例如 Composer、Laravel 等。

假设你对后来新兴的前端开发方式,有一定的了解,包括不限于 Vue、React、Node.js、Webpack 的相关使用,插件的开发会贯穿前后端相关知识。

假设你已经有基础的运维知识,例如 MySQL、Nginx 等相关套件的使用。

同时,你需要有一定的故障排查能力、相对良好的编码习惯、相关文档或知识的检索能力。

若没有以上基础,以下的工作会给你带来一定的难度。

如果你对 PHP 语言存在兴趣,我非常推荐通过 php.net 官网进行学习,或者通过 B 站等视频课程,其他技能的学习也是一样,这需要花费一定的精力和时间。

接下来

让我们来了解什么是 Flarum 。

这是一个非常新潮的社区/论坛框架,目前有非常活跃的开源社区支持,官网对他的介绍是:Modern, fast, and free!

他基于 PHP Laravel 框架进行二次开发, 界面采用高性能且小巧的 JavaScript 框架 Mithril

他以 MIT 许可证 发布。

有关他的更多介绍或一些预览,可以通过 关于 Flarum 或以下链接进行了解:

如果你想知道有哪些人正在使用 Flarum 框架搭建社区,FlarumCN 提供了 社区展 入口进行展示,这看起来非常不错。

源码推荐

推荐几个具有代表性的插件,在开发过程中,或许能给你带来不少帮助和参考。

站外插件

在后续的开发中,如果你疑惑某个功能的实现方式,大部分情况下,可以从 Flarum 社区或开源项目源码中寻找到答案。

站内插件

每个 Flarum 站点都有各自的群体和特点,HamCQ 社区也不例外,这里我也例举几个站内插件,方便后续对接开发。

其中:

二次开发:基于别人已经写好的插件,进行改造适配
Public:仓库文件公开访问
Private:考虑站内安全因素,不开放访问,如果需要可以联系我(要是一名业余无线电爱好者那就更好了)

跑起来

Flarum 环境

将 Flarum 框架运行在你的开发环境,是必不可少的。

安装 | Flarum 中有非常详细的介绍,你可以先有一个大概的了解。

不过,我想在这里介绍另外一种本地开发的运行方式。

对于 PHP、Composer、MySQL、Node.js、Webpack 等本地环境的部署,这里不再赘述。

鉴于前后端环境共存的工程项目,个人非常建议使用 VSCode 编码工具进行开发,做一些简单的改造:

  • Git Bash 终端环境(Windows)
  • VSCode 插件: PHP Intelephense

拉取 Flarum 源码文件,Repo 地址:https://github.com/flarum/flarum

git clone git@github.com:flarum/flarum.git --depth=1

在工程项目根目录中,打开 VSCode 终端,首先进行:

composer install

然后

cd public/

执行

php -S 127.0.0.1:8888

在浏览器访问:http://127.0.0.1:8888/

就可以得到看到 Install Flarum 的字样

填写完数据库配置内容,便可以得到一个开发插件的基础环境。

空白扩展生成器

接下来,需要在 Flarum 环境中,创建一个你自己的插件开发工程项目,可以使用社区提供的扩展生成器来完成:

这个帖子中,看到更具体的讨论:Create Flarum Extension by FriendsOfFlarum

参考 Flarum 的插件扩展的开发文档,它提供了一种本地开发时候加载模块的方式(英文介绍),约定 Flarum 本地的扩展包都放在 packages/ 目录下

为了不影响刚刚启动的 php -S 127.0.0.1:8888 服务,我们可以用 VSCode 多开终端,在新的终端中运行:

composer config repositories.0 path "packages/*"

如果你想知道更多细节,这里有个不错的介绍,可以前往 Flarum 二次开发项目配置指南 查看,其中,有关版本控制环节,个人建议可以把 package/* 中的每个文件夹当做一个项目管理即可。

现在,可以安装插件生成器,以便后续的多个插件开发:

npm install -g @friendsofflarum/create-flarum-extension

在上一步创建的扩展包目录中,继续使用如下命令,生成空白的内容填充:

create-flarum-extension [dir]

例如,你可以在项目根目录下执行:

create-flarum-extension packages/flarum-ext-hamzone-tools

成功后,你会得到如下画面,他将会引导你创建第一个插件内容

如果你不知道具体进行哪些选项,这里给出一份预览:

于是,你的工程项目文件夹,可能会是这样的:

有关示例中的 flarum-ext-hamzone-tools 插件内容,会在下一章节中进行说明。

启用插件

上一步操作中,成功生成了插件模板,这时候他已经具备运行的基础文件,但是还需要做一点简单的改动,让他可以在 Flarum 后台中进行启用。

项目根目录的 composer.json 文件中,对应 require 字段添加:

"require": {
      "hamzone/flarum-ext-hamzone-tools": "*@dev"
}

在 flarum 的配置文件中,修改如下:

'debug' => true,

项目根目录中运行终端,执行:

composer require hamzone/flarum-ext-hamzone-tools @dev

在 MacOS 中运行如上??指令,可能会提示报错:zsh: no matches found,可以尝试在 ~/.zshrc 中添加:

setopt no_nomatch 

后台控制面板中,便出现了刚刚生成的插件:

不过,当你点击开关,准备开启插件的时候,出现了一个报错:An error occurred while trying to load this page.

不要慌,我们可以去 storage/logs 文件夹中,查看报错的具体信息:

[2023-01-13 15:48:15] flarum.ERROR: InvalidArgumentException: File not found at path: flarum-ext-template\flarum\packages\flarum-ext-hamzone-tools/js/dist/admin.js......

很明显,缺少了前端所需的 dist 文件,只需前往 packages/flarum-ext-hamzone-tools 中的 js 文件夹分别执行:

yarn install
yarn build

再次访问后台界面,即可开启插件,并获得默认输出:[hamzone/flarum-ext-hamzone-tools] Hello, admin!

至此,已经成功通过本地开发环境,运行了第一个 Flarum 插件。

我在现有稀少的文档中,主要参考了以下帖子,感谢他们的付出:

如果你还有任何疑问,可以入群讨论:HamCQ 社区交流群
(此群主要面向 业余无线电爱好者 && 开发者)

Prev:
Next:

发表回复

您的电子邮箱地址不会被公开。 必填项已用 * 标注