打包

配置

在开始写扩展之前，你需要在系统上配置如下几个工具：

  • 下载并全局安装 Composer ，为扩展生成自动加载。
  • 配置 Node.js 并全局安装 Gulp ，编译扩展的客户端 JavaScript。

除此之外，你也可以安装 Flarum 的 Vagrant 开发者镜像，它帮你自动装好了所有工具。

生成框架

Flarum 有便利的工具来为你生成扩展的框架，这样你就可以马上开始写代码了。打开终端并在论坛根目录运行下面的命令：

  1. php flarum/flarum generate:extension

工具会向你咨询一些细节。扩展名是扩展独一无二的名称，只能包含数字、字母和连字符(-).命名空间用来分离你的代码；你可以把提供者名字加扩展名(例如 Tobscure\Attachments)作为命名空间.

一旦你填完所有细节，工具会在你论坛根目录的 extensions 目录下创建一个新目录。完成这些可能会花费几分钟的时间。下面让我们看下生成了些什么：

  • bootstrap.php 如果你的扩展被启用， Flarum 会在每当有请求时加载这个文件。这个文件是扩展启动的地方！你不应该修改它。
  • flarum.json 包含你扩展的元信息(标题、描述、作者、依赖项)。更多信息请往下看。
  • js/ 存放扩展的 JavaScript 文件。你将在扩展客户端了解到更多。
  • less/ 存放扩展的 CSS 文件。你将在主题了解到更多。
  • locale/ 存放扩展的翻译文件。你将在国际化了解到更多。
  • migrations/ 当扩展被安装/升级/卸载时会运行数据迁移。你将在域扩展了解到更多。
  • src/ 存放扩展的后端源代码，将被使用 PSR-4 标准的 Composer 自动加载。

flarum.json

文档待写。

事件订阅者

就像你从介绍里了解到的一样，扩展工作的唯一方式就是监听和响应事件。让我们看下这是如何实现的。

我们将从头开始。如果你看过 bootstrap.php ，你会发现它返回一个扩展类的名字。如果扩展启用了，在每个请求的开始，Flarum 会包含这个文件并且把这个类注册为一个服务提供者。这个类是你处理事务的关键。

我们再继续看，Flarum 在 src 目录下生成了这个类。如果你仔细看，你会发现这个独立的方法:

  1. public function listen(Dispatcher $events)
  2. {
  3.     $events->subscribe('Your\Namespace\Listeners\AddClientAssets');
  4. }

当事件系统建立起来后，Flarum 就会调用每个扩展服务提供者的 listen 方法。它传递一个 Laravel 的消息分发实体，因此你能如你所愿得监听事件。

但我们在这做了些不同的事。我们调用 subscribe 方法去注册一个事件订阅者而不是直接添加事件监听器. 订阅者是分组相关事件监听器的一种，它能帮助你组织代码。你可以按你喜欢的方式组织你的事件监听器，但 Flarum 的附带扩展采用订阅者的任务 + 订阅者名(例如 AddClientAssets 或 AddApiAttributes )的约定。

好了，让我们再看下生成的 AddClientAssets 监听器。

  1. use Flarum\Events\RegisterLocales;
  2. use Flarum\Events\BuildClientView;
  3. use Illuminate\Contracts\Events\Dispatcher;
  5. class AddClientAssets
  6. {
  7.     public function subscribe(Dispatcher $events)
  8.     {
  9.         $events->listen(RegisterLocales::class, [$this, 'addLocale']);
  10.         $events->listen(BuildClientView::class, [$this, 'addAssets']);
  11.     }

这是我们注册事件监听器的地方。我们导入 event 类，然后在订阅者的 subscribe 方法里调用分发器的 listen() ， 传递的参数是我们希望订阅的事件名称和处理事件的方法。

这些特定的事件监听器用来处理默认的本地化语言包、JavaScript 和 CSS 文件，这些都是在创建扩展的时候由系统自动生成。你可以在扩展客户端章节了解到关于他们得更多信息。

译者：@theFool32