Updating For Beta 8
All extensions will need to be refactored in order to work with beta 8. Here are the main things you will need to do in order to make your extension compatible.
caution
This guide is not comprehensive. You may encounter some changes we haven't documented. If you need help, start a discussion on the community forum or Discord chat.
Beta 8 comes with large changes to the overall structure of the PHP backend. You will need to look through this list of namespace changes and make changes to your extension accordingly.
This script can help you to automate most of the namespace changes. Of course, you should still test your extension after running the script as it may miss something.
Many database columns and JSON:API attributes have been renamed to conform to a convention. You will need to update any instances where your extension interacts with core data. You can see the changes in #1344.
Beta 8 introduces a new concept called extenders that replace the most common event listeners. You can learn more about how they work in the updated extension docs.
bootstrap.php
has been renamed to extend.php
and returns an array of extender instances and functions:
use Flarum\Extend;
return [
(new Extend\Frontend('forum'))
->js(__DIR__.'/js/dist/forum.js')
->css(__DIR__.'/less/forum.less')
->route('/t/{slug}', 'tag')
->route('/tags', 'tags'),
function (Dispatcher $events) {
$events->subscribe(Listener\AddForumTagsRelationship::class);
}
]
If you're listening for any of the following events, you'll need to update your code to use an extender instead. See the relevant docs for more information.
Event | Extender |
---|---|
Flarum\Event\ConfigureFormatter * | Flarum\Extend\Formatter |
Flarum\Event\ConfigureWebApp * | Flarum\Extend\Frontend |
Flarum\Event\ConfigureClientView * | Flarum\Extend\Frontend |
Flarum\Event\ConfigureLocales | Flarum\Extend\Locales |
Flarum\Event\ConfigureApiRoutes | Flarum\Extend\Routes |
Flarum\Event\ConfigureForumRoutes | Flarum\Extend\Routes |
* class no longer exists
Previously Flarum and its extensions used a custom Gulp workflow to compile ES6 source code into something that browsers could understand. Beta 8 switches to a more conventional approach with Webpack.
You will need to tweak the structure of your extension's js
directory. Currently, your JS file hierarchy looks something like the following:
js
├── admin
│ ├── src
│ │ └── main.js
│ ├── dist
│ │ └── extension.js
│ ├── Gulpfile.js
│ └── package.json
└── forum
├── src
│ └── main.js
├── dist
│ └── extension.js
├── Gulpfile.js
└── package.json
You'll need to make the following changes:
Update
package.json
and createwebpack.config.js
,forum.js
, andadmin.js
files using these templates.Inside your
admin
andforum
folders, deleteGulpfile.js
,package.json
, anddist
. Then inside eachsrc
folder, renamemain.js
toindex.js
. Now move all of thesrc
files outside ofsrc
folder and delete it.In the root
js
folder create a folder calledsrc
and move youradmin
andforum
folders into it.While still in your root
js
folder, runnpm install
and thennpm run build
to build the new JS dist files.
If everything went right, your folder structure should look something like this:
js
├── src
│ ├── admin
│ │ └── index.js
│ └── forum
│ └── index.js
├── dist
│ ├── admin.js
│ ├── admin.js.map
│ ├── forum.js
│ └── forum.js.map
├── admin.js
├── forum.js
├── package.json
└── webpack.config.js
Take a look at the bundled extensions for more examples.
Beta 8 upgrades to Font Awesome 5, in which icon class names have changed. The flarum/helpers/icon
helper now requires the full Font Awesome icon class names to be passed, eg. fas fa-bolt
.