Flarum 论坛插件开发教程

Flarum 是一个现代化的开源论坛软件，基于 PHP 的 Laravel 框架和前端 JavaScript 框架 Mithril.js，拥有强大的扩展性。本教程将指导你从零开始开发一个简单的 Flarum 插件，涵盖环境准备、插件结构、开发流程和发布步骤。

---

第一步：准备开发环境

在开发 Flarum 插件之前，你需要确保本地开发环境满足以下要求：

1.1 环境要求

• PHP：7.4 或更高版本，需启用以下扩展：
• fileinfo, mbstring, openssl, pdo_mysql, tokenizer, xml, ctype, json, gd, zip
• Composer：PHP 的依赖管理工具，用于安装 Flarum 和插件依赖。
• Node.js 和 npm：用于前端资源编译（如 JavaScript 和 CSS）。
• MySQL：5.7 或更高版本，支持 utf8mb4 字符集。
• Web 服务器：推荐 Nginx 或 Apache。
• Git：用于版本控制。

1.2 安装 Flarum

1. 安装 Composer：

• 如果未安装 Composer，可在终端运行以下命令（Linux/macOS）：
  bash php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" php composer-setup.php php -r "unlink('composer-setup.php');" mv composer.phar /usr/local/bin/composer
• 验证安装：composer --version

1. 创建 Flarum 项目：

• 在空目录下运行以下命令安装 Flarum：
  bash composer create-project flarum/flarum . --stability=stable
• 这将在当前目录安装 Flarum 的稳定版本。

1. 配置 Web 服务器：

• Nginx 示例配置（参考）： server { listen 80; server_name yourwebsite.com; root /path/to/flarum/public; index index.php index.html; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } }
• 将 yourwebsite.com 替换为你的域名，root 路径指向 Flarum 的 public 目录。

1. 配置数据库：

• 创建 MySQL 数据库：
  sql CREATE DATABASE flarum_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; GRANT ALL ON flarum_db.* TO 'flarum_user'@'localhost' IDENTIFIED BY 'your_password'; FLUSH PRIVILEGES;
• 访问 Flarum 的安装向导（http://yourwebsite.com），输入数据库信息完成安装。

1. 安装 Node.js 和 npm：

• 安装 Node.js（推荐 LTS 版本）：
  bash curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs
• 验证：node --version 和 npm --version

1. 安装前端依赖：

• 在 Flarum 根目录运行：
  bash npm install

---

第二步：创建插件骨架

Flarum 提供了 flarum-cli 工具来快速生成插件骨架。以下是创建插件的步骤：

2.1 安装 flarum-cli

• 全局安装 flarum-cli：

  composer global require flarum/cli

• 确保 Composer 的全局 bin 目录在环境变量中：

  export PATH="$HOME/.composer/vendor/bin:$PATH"

2.2 生成插件骨架

1. 在 Flarum 根目录创建一个 packages 文件夹，用于存放本地开发的插件：

   mkdir packages && cd packages

2. 使用 flarum-cli 生成插件：

   flarum-cli init

3. 根据提示输入插件信息：

• Package name：如 your-vendor-name/your-extension-name（例如 acme/hello-world）
• Extension name：插件名称（例如 Hello World）
• Description：插件描述
• Namespace：PHP 命名空间（例如 Acme\HelloWorld）
• License：推荐 MIT

完成后，flarum-cli 会在 packages 目录下生成一个插件目录（例如 hello-world），结构如下：

hello-world/
├── composer.json
├── src/
├── js/
│   ├── src/
│   │   ├── admin/
│   │   ├── forum/
│   │   └── common/
│   ├── package.json
│   └── webpack.config.js
├── resources/
│   ├── locales/
│   └── less/
├── migrations/
└── README.md

2.3 配置 Composer

• 编辑 Flarum 根目录的 composer.json，在 repositories 中添加本地插件路径：

  "repositories": [
      {
          "type": "path",
          "url": "packages/*"
      }
  ]

• 安装插件：

  composer require acme/hello-world:*

• 清除缓存：

  php flarum cache:clear

2.4 启用插件

• 访问 Flarum 后台（http://yourwebsite.com/admin），在「扩展」页面启用你的插件（Hello World）。

---

第三步：开发一个简单插件

我们将开发一个简单的插件，在论坛帖子页面添加一个「点赞」按钮，点击后显示一个弹窗消息。

3.1 后端开发

1. 创建后端逻辑：

• 在 src 目录下创建一个文件 Extend.php： <?php namespace Acme\HelloWorld; use Flarum\Extend; use Flarum\Api\Controller\ShowDiscussionController; return [ (new Extend\Frontend('forum')) ->js(__DIR__ . '/js/dist/forum.js') ->css(__DIR__ . '/resources/less/forum.less'), (new Extend\Routes('api')) ->post('/hello-world', 'hello-world.like', ShowDiscussionController::class), ];
• 说明：
  • Extend\Frontend：注册前端资源（JS 和 CSS）。
  • Extend\Routes：添加一个 API 路由 /api/hello-world，用于处理点赞请求。

1. 添加 API 控制器：

• 在 src 目录下创建 Controllers/LikeController.php： <?php namespace Acme\HelloWorld\Controllers; use Flarum\Api\Controller\AbstractCreateController; use Psr\Http\Message\ServerRequestInterface; use Tobscure\JsonApi\Document; use Illuminate\Support\Arr; class LikeController extends AbstractCreateController { public function data(ServerRequestInterface $request, Document $document) { $user = Arr::get($request->getQueryParams(), 'user'); return ['message' => "Hello, $user! You liked this post!"]; } }

3.2 前端开发

1. 配置前端环境：

• 进入插件的 js 目录：
  bash cd packages/hello-world/js npm install
• 编译前端资源：
  bash npm run build

1. 添加前端代码：

• 编辑 js/src/forum/index.js： import { extend } from 'flarum/extend'; import DiscussionPage from 'flarum/components/DiscussionPage'; import Button from 'flarum/components/Button'; app.initializers.add('acme-hello-world', () => { extend(DiscussionPage.prototype, 'sidebarItems', function (items) { items.add('likeButton', m(Button, { className: 'Button Button--primary', onclick: () => { fetch('/api/hello-world', { method: 'POST', body: JSON.stringify({ user: app.session.user.username() }) }) .then(response => response.json()) .then(data => alert(data.message)); } }, 'Like This Post')); }); });

1. 添加样式：

• 编辑 resources/less/forum.less：
  less .Button--like { margin-top: 10px; }

3.3 国际化（i18n）

• 在 resources/locales 下创建 en.yml 和 zh.yml：

  # en.yml
  acme-hello-world:
    forum:
      button: Like This Post

  # zh.yml
  acme-hello-world:
    forum:
      button: 点赞此帖

• 更新 js/src/forum/index.js，使用翻译：

  items.add('likeButton', m(Button, {
      className: 'Button Button--primary',
      onclick: () => {
          fetch('/api/hello-world', {
              method: 'POST',
              body: JSON.stringify({ user: app.session.user.username() })
          })
          .then(response => response.json())
          .then(data => alert(data.message));
      }
  }, app.translator.trans('acme-hello-world.forum.button')));

---

第四步：测试插件

1. 编译和部署：

• 重新编译前端资源：
  bash cd packages/hello-world/js npm run build
• 清除 Flarum 缓存：
  bash cd ../../.. php flarum cache:clear

1. 测试：

• 访问论坛帖子页面，检查是否出现「Like This Post」按钮。
• 点击按钮，确认是否弹出包含用户名的消息。

---

第五步：发布插件

1. 整理插件文件：

• 确保 composer.json 包含正确的信息：
  json { "name": "acme/hello-world", "description": "A simple Flarum extension that adds a like button.", "type": "flarum-extension", "require": { "flarum/core": "^1.0" }, "autoload": { "psr-4": { "Acme\\HelloWorld\\": "src/" } }, "extra": { "flarum-extension": { "title": "Hello World", "icon": { "name": "fas fa-thumbs-up", "backgroundColor": "#e74c3c", "color": "#fff" } } } }

1. 发布到 GitHub：

• 初始化 Git 仓库：
  bash cd packages/hello-world git init git add . git commit -m "Initial commit"
• 推送到 GitHub：
  bash git remote add origin https://github.com/your-username/hello-world.git git push -u origin master

1. 发布到 Packagist：

• 登录 Packagist，提交你的 GitHub 仓库。
• 其他用户可通过 Composer 安装：
  bash composer require acme/hello-world

---

第六步：常见问题和注意事项

1. 插件冲突：

• 确保你的插件不与现有插件冲突，检查依赖版本。
• 使用 composer update 更新依赖，运行 php flarum migrate 执行数据库迁移。

1. 调试：

• 启用 Flarum 的调试模式，在 config.php 中设置：
  php 'debug' => true,
• 检查日志文件（storage/logs）以排查错误。

1. 性能优化：

• 避免在前端加载过多 JavaScript 或 CSS。
• 使用 WebSocket（Flarum 默认支持）实现实时功能。

1. 社区资源：

• 参考 Flarum 官方文档 和 Flarum 中文社区。
• 插件市场：https://extiverse.com/

---

第七步：进阶开发

1. 数据库操作：

• 在 migrations 目录下创建迁移文件，定义数据库表结构：
• <?php use Illuminate\Database\Schema\Blueprint; use Flarum\Database\Migration; return Migration::createTable('likes', function (Blueprint $table) { $table->increments('id'); $table->integer('post_id')->unsigned(); $table->integer('user_id')->unsigned(); $table->timestamps(); });

1. 事件监听：

• 监听 Flarum 事件（如帖子创建）：
  php (new Extend\Event()) ->listen(\Flarum\Post\Event\Posted::class, function ($event) { // 自定义逻辑 }),

1. 权限管理：

• 添加自定义权限：
  php (new Extend\Policy()) ->modelPolicy(\Flarum\Post\Post::class, Access\PostPolicy::class),

---

总结

通过本教程，你已经学会了如何搭建 Flarum 开发环境、创建插件骨架、开发前后端功能、支持国际化、测试和发布插件。Flarum 的扩展性非常强大，结合其 REST API 和模块化设计，你可以实现几乎任何论坛功能。继续探索 Flarum 官方文档和社区资源，开发更复杂的插件！