跳到主要内容

开始

想打造一个 Flarum 扩展? 来对地方了! 本文档将带您了解一些基本概念,之后您将从头开始打造您的第一个 Flarum 扩展。

架构

为了理解如何扩展 Flarum,我们需要先明白 Flarum 是如何构建的。

要知道,Flarum 使用了一些 现代 语言和工具。 如果您以前只构建过 WordPress 的插件,您可能会觉得有点力不从心。 没有关系 —— 这是一个学习新事物和扩展技能的好机会。 不过我们建议您在开始之前先熟悉一下下面描述的技术。

Flarum 的构成有三层:

  • 第一层,后端。 后端用 面向对象的 PHP 语言编写,并通过 Composer 使用了大量的 Laravel 组件和其他资源包。 您还需要熟悉 依赖项注入 的概念,它在整个后端中都有使用。

  • 第二层,后端开放的一个 公共 API,允许前端客户端与论坛数据进行交互。 该接口根据 JSON:API 规范 构建。

  • 第三层,默认的 Web 界面,俗称 前端。 这是一个使用 API 的 单页应用,由一个简单的类 React 框架 Mithril.js 构建。 It's built with a simple React-like framework called Mithril.js.

扩展程序通常需要与这三层都进行交互才能有所为。 例如,如果您想创建一个可以在用户资料中添加新属性的扩展,则需要在 后端 中添加相应的数据库结构,通过 公共 API 调用该数据,然后在 前端 显示这个数据并允许用户修改它。

那…… 如何扩展这些层呢?

扩展器

为了扩展 Flarum,我们需要用到 扩展器,让我们先了解一下它的概念。 扩展器其实就是 声明性 对象,您可以通过简单的方式描述想要实现的内容(比如向论坛添加新的路由,或者在创建新主题帖时执行某些代码)。

每个扩展器都是不同的,但是大体上长这样: However, they will always look somewhat similar to this:

// 注册要交付给前端的 JavaScript 和 CSS 文件
(new Extend\Frontend('forum'))
->js(__DIR__.'/forum-scripts.js')
->css(__DIR__.'/forum-styles.css')

您首先创建一个扩展器实例,然后调用方法以对其进行进一步配置。 所有方法都将返回结果到该扩展器本身,因此您只需要通过链式方法调用就可以实现您的整个配置。

为了保持一致,我们在后端(PHP)和前端(JavaScript)都使用了扩展器的概念。 您在扩展中做的 每一件事 都应当通过扩展器来完成,因为扩展器是我们给予您的 保证 —— 保证 Flarum 小版本更新绝对不破坏您的扩展。

所有 Flarum 核心提供的可用扩展器都可以在 Extend 命名空间(PHP API 文档)找到。

Hello World

想亲眼看看一个扩展器的执行? Flarum 安装根目录中的 extend.php 是为您的站点注册扩展器的最简单的途径,它应该会返回一个扩展器对象的数组。 It should return an array of extender objects. 打开该文件并添加以下内容:

<?php

use Flarum\Extend;
use Flarum\Frontend\Document;

return [
(new Extend\Frontend('forum'))
->content(function (Document $document) {
$document->head[] = '<script>alert("你好,世界!")</script>';
})
];

现在,访问您的论坛,接受真挚的问候(尽管很突兀)。 👋

对于简单的网站定制,比如添加一些自定义的 CSS 或 JavaScript,或者整合您网站的认证系统,论坛根目录下的 extend.php 文件是非常好用的。 但是在某些时候,您的自定义可能会超出它的限制范围。 或者您想建立一个扩展程序,并分享到社区,那么是时候建立一个扩展程序了! Time to build an extension!

打包扩展程序

Composer 是 PHP 的一个依赖管理工具。 它允许应用程序轻松地拉取外部代码库,并保持他们是最新的,以便及时应用安全补丁和错误修复。

如上所述,每个 Flarum 扩展程序也是一个 Composer 包。 这意味着一个人可以「require」某个扩展程序,Composer 会把它拉取给 Flarum,同时使扩展程序保持最新版本。 Nice!

在开发过程中,您可以在本地处理您的扩展程序,并建立一个 Composer 本地路径仓库 以安装您的本地副本。 在 Flarum 安装根目录下创建一个新的 packages 文件夹,然后运行这个命令来告诉 Composer 它可以在这里找到软件包:

composer config repositories.0 path "packages/*"

现在,来构建我们的第一个扩展程序吧。 在 packages 里面为您的扩展程序建立一个新的文件夹,命名为 hello-world。 我们会在里面放两个文件:extend.phpcomposer.json。 这些文件是扩展程序的心脏和灵魂。

extend.php

扩展程序的 extend.php 跟您站点根目录下的那个是一模一样的,它会返回一个扩展器对象数组,并告诉 Flarum 您想要做什么。 It will return an array of extender objects that tell Flarum what you want to do. 现在,将前面我们操作的 Frontend 扩展器移动到这里。

composer.json

我们需要告诉 Composer 一些您的软件包的信息,创建 composer.json 文件已写入这些信息:

{
"name": "acme/flarum-hello-world",
"description": "向世界问好!",
"type": "flarum-extension",
"require": {
"flarum/core": ">=0.1.0-beta.16 <=0.1.0"
},
"autoload": {
"psr-4": {"Acme\\HelloWorld\\": "src/"}
},
"extra": {
"flarum-extension": {
"title": "Hello World",
"icon": {
"name": "fas fa-smile",
"backgroundColor": "#238c59",
"color": "#fff"
}
}
}
}
  • name,名字。 是 Composer 软件包的名字。 格式是 供应商/包名

    • 您需要起一个全世界独一无二的供应商名,或者可以直接沿用 GitHub 的用户名。 以本教程为例,这里我们假设 acme 是您的供应商名。
    • 您应该给包 包名 加上 flarum- 前缀,以指明此包是专门给 Flarum 用的。
  • description,描述。 用一句话描述这个扩展程序的作用是什么。

  • type,类型。 只能是 flarum-extension。 这确保了当别人「require」您的扩展程序时,能被正确识别。

  • require,依赖。 描述您的扩展程序自身的依赖关系。

    • 您需要在这里指定您的扩展程序所兼容的 Flarum 版本。
    • 这里也是列出您的代码需要使用的 Composer 外部工具库的地方。
  • autoload,定义一个从命名空间到目录的映射,告诉 Composer 在哪里可以找到扩展程序的类。 此处的命名空间应以 驼峰写法 反映扩展程序的供应商和包名.

  • extra.flarum-extension,包含一些 Flarum 特有的信息,比如您扩展程序在论坛的显示名称以及图标。

    • title 您的扩展程序的显示名称。
    • icon 是一个定义您扩展程序图标的对象。 name 属性是 Font Awesome 图标名。 剩下的都被用作图标的 style 属性。

请参阅 composer.json 模式 文档,以获取有关可以添加到 composer.json 中的其他属性的信息。

使用 FoF 扩展生成器 自动创建扩展程序的基架。

$ flarum-cli init

安装您的扩展

最后一步就是安装您的扩展。 进入 Flarum 安装根目录,执行以下命令:

composer require acme/flarum-hello-world *@dev

执行完成后,前往您论坛后台管理面板启用插件,最后回到您的论坛。

whizzing, whirring, metal clunking

哇! 你好,扩展!

很好,我们取得了一些进展。 我们学习了如何设置扩展和使用扩展,打开了新世界的大门。 继续阅读以了解如何扩展 Flarum 的前端。