跳到主要内容

开始

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

架构​

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

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

Flarum 的构成有三层：

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

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

  • 第三层，默认的 Web 界面，俗称 前端。 这是一个使用 API 的 单页应用， 由一个简单的类 React 框架 Mithril.js 构建。

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

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

扩展器​

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

每个扩展器都是不同的， 但是大体上长这样：

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

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

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

所有 Flarum 核心提供的可用扩展器都可以在 Extend 命名空间(PHP API 文档)中找到。扩展程序亦有可能提供他们自有的扩展器。

世界你好​

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

<?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 文件是非常好用的。 但是在某些时候，您的自定义可能会超出它的限制范围。 或者您想建立一个扩展程序，并分享到社区。 那么是时候建立一个扩展程序了！

打包扩展程序​

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

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

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

composer config repositories.0 path "packages/*"

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

extend.php​

扩展程序的 extend.php 跟您站点根目录下的那个是一模一样的。 它会返回一个扩展器对象数组，并告诉 Flarum 您想要做什么。 现在，将前面我们操作的 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 中的其他属性的信息。

Flarum CLI

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

$ flarum-cli init

安装您的扩展​

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

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

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

啾，咻，铮铛

哇！ 你好，扩展！

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