Updating For 2.0

Flarum 2.0 is a major release that includes a number of breaking changes and new features. This guide will help you update your extension to be compatible with Flarum 2.0 and take advantage of the new additions.
If you need help applying these changes or using new features, please start a discussion on the community forum.
Upgrade Automation
You can use the Flarum CLI to automate as much of the upgrade steps as possible:
Keep in mind the following information about the upgrade command:
- The process goes through multiple steps, each step points to the related documentation, and provides helpful tips.
- After each step, the changes are committed to Git so that you can always review the changes commit by commit.
- Mistakes can and will be made, after every step is finished you can view the changes made and make any necessary adjustments.
- Most of the steps should require little to no manual adjustments, except for the following:
- Adapt to accessing/extending lazy loaded Flarum modules. (Can require some amount of manual changes)
- Prepare for JSON:API changes. (100% manual changes requires)
- Search & Filter API changes. (Can require some amount of manual changes)
Cài đặt
The upgrader is just another command of the @flarum/cli npm package.
npm install -g @flarum/cli@3
v3 of the CLI is only compatible with v2.x of Flarum, if you wish to continue using the CLI for both v1.x and v2.x of Flarum, you can install them together. Read more about it here.
Sử dụng
Now to use, simply run the following command:
fl upgrade 2.0
Before you use the automated upgrade command, make sure to read the entire upgrade guide at least once to understand the changes.
Frontend
Dependencies
Breaking
In package.json:
- Set
flarum-webpack-configto^3.0.0. - Set
flarum-tsconfigto^2.0.0.
Mithril 2.2
Breaking
- Flarum 2.0 upgrades Mithril to version 2.2. This version introduces one breaking change that may affect your extension. Mithril no longer sets a
textattribute on vnodes, instead it uses a child with the tag#. So to extract text from a vnode, use theextractText()utility instead.
Export Registry
2.0 introduces a new concept called the Export Registry. This is a central place where exports from core and extensions are automatically registered. This allows extensions to easily extend modules from other extensions without those extensions needing to explicitly support it. This also allows lazy loading of modules, which can improve performance.
Compat API
Breaking
- The compat API has been removed, for most extensions this should not be a problem. If you are using the compat API to allow other extensions to extend your modules, you can drop it and instead just make sure all your modules are imported to be automatically registered. For example, tags in 1.x used the compat API to expose its modules. In 2.0 insuring the modules are imported is enough.
Importing Modules
Breaking
- Importing from extensions must now be done using a
ext:prefix. This means that any imports you are currently making from bundled extensions will need to be updated. For example,flarum/tags/common/models/Tagbecomesext:flarum/tags/common/models/Tag. This also means you can import from any other extension, not just bundled ones, using the same syntax ofext:vendor/extension/common/....// Beforeimport Tag from 'flarum/tags/common/models/Tag';// Afterimport Tag from 'ext:flarum/tags/common/models/Tag'; - Importing from
@flarum/coreno longer works. It was previously only allowed for the compat API. - The
useExtensionswebpack option has been removed, use the import format explained above to import using the export registry instead. - Some flarum modules are now lazy loaded, such as
LogInModal. You have to make sure they have been loaded before using them, or you can trigger the loading yourself. See the Code Splitting documentation for more information.
Read more about the export registry and how to use it in the Export Registry documentation.
Familiarize yourself with the new Code Splitting feature to lazy load modules and improve overall performance.
Forum Search
Breaking
- The forum search UI has been refactored to use a new
SearchModalcomponent. - The
flarum/forum/components/Searchcomponent is no longer the global search component, it can still be used for custom search purposes. - Custom global search sources should be registered in
flarum/forum/components/GlobalSearchsourceItemsmethod. - Custom global search sources should now implement the
GlobalSearchSourceinterface instead ofSearchSource, see https://github.com/flarum/framework/blob/2.x/framework/core/js/src/common/components/AbstractGlobalSearch.tsx#L26-L69. - The
flarum/forum/states/SearchStateclass has been moved toflarum/common/states/SearchState.
Admin Search
Notable
- The admin dashboard now has a search feature, as long as you register your settings/permissions using the
Adminextender, then they will be automatically picked up. - If your settings/permissions are too custom to be added through the
Admin.settingandAdmin.permissionextenders, then you can useAdmin.generalIndexItemsto add custom search index entries.
Trang tổng quan quản trị
Breaking
- The old extension grid widget on the admin dashboard, which displayed all installed extensions grouped by category, has been removed. It duplicated the information already available in the sidebar and provided no additional value.
Notable
- A new Extension Health Widget has been added to the admin dashboard. It surfaces actionable information about installed extensions:
- Abandoned — extensions whose Composer package is marked abandoned on Packagist, with or without a suggested replacement.
- Suggested — packages listed in the
suggestfield of any enabled extension'scomposer.jsonthat are not yet installed. - Disabled — a compact icon grid of all installed-but-disabled extensions.
- Abandoned extensions also display a warning badge on their entry in the admin sidebar.
- See the Extension Health Widget docs for how to use the
abandonedandsuggestfields in your own extension'scomposer.json.
Locale
Breaking
-
HTML tags used within translations must be simple tags, without attributes. For example, if you have a locale with the value:
my_locale_key: "You can read about a <a href='{basic_impl_link}'>basic queue</a> implementation or a <a href='{adv_impl_link}'>more advanced</a> one."You must change this to:
my_locale_key: "You can read about a <basic_impl_link>basic queue</basic_impl_link> implementation or a <adv_impl_link>more advanced</adv_impl_link> one."With the following code in your JavaScript:
app.translator.trans('acme.my_locale_key', {basic_impl_link: <a href="https://discuss.flarum.org/d/28151-database-queue-the-simplest-queue-even-for-shared-hosting" />,adv_impl_link: <a href="https://discuss.flarum.org/d/21873-redis-sessions-cache-queues" />,}) -
Tags used within translations such as
<strong>were previously auto provided as parameters
Miscellaneous
There have been many changes to the core frontend codebase, including renamed or moved methods/components, new methods/components, and more. It might help to look directly at the JavaScript diffs to see what has changed. But here are some notable changes.
Breaking
app.extensionDatahas been renamed toapp.registry, but you should now use theAdminextender instead. ItsgetAllExtensionPermissions()method has been renamed togetAllPermissions().- Some extension initializers have been renamed to be more uniform, if you are checking for initializer existence with
app.initializers.has('...')you should update the name accordingly. IndexPage.prototype.sidebarhas been removed, use theIndexSidebarcomponent instead.IndexPage.prototype.navItemshas been moved toIndexSidebar.prototype.navItems.IndexPage.prototype.sidebarItemshas been moved toIndexSidebar.prototype.items.IndexPage.prototype.currentTaghas been moved toapp.currentTag.- The
UploadImageButtoncomponent has been refactored to allow using it in different contexts. An admin setting definition has also been added to allow you to use an upload setting directly. Additionally, the component has been moved to thecommonnamespace. - The
FieldSetcomponent has been refactored. - The
avatarandiconhelpers have been refactored to newAvatarandIconcomponents. Which now allows you to extend them to modify their behavior. - The
Modalcomponent has been split intoModalandFormModal. TheModalcomponent is now a simple modal that can be used for any content, while theFormModalcomponent is a modal that is specifically designed for forms.
Notable
-
A Reset Settings button is now available on extension admin pages. For extensions using the standard
Admin.setting()extender, the button appears automatically alongside the save button. If your extension has a custom settings page, you should add the reset button yourself by callingthis.resetButton()in yourcontent()method. Pass a label as the third argument tothis.setting()so the modal can display human-readable names for each key:content() {const myValue = this.setting('acme.my_key', '', app.translator.trans('acme.admin.my_key_label'));return (<Form>{/* ... your form fields ... */}<div className="Form-group Form-controls">{this.submitButton()}{this.resetButton()}</div></Form>);}Confirming the reset deletes the listed setting rows from the database and reloads the page, reverting them to their PHP-side defaults. A
Flarum\Settings\Event\Resetevent is dispatched on the backend with the$actor,$extensionId, and$keysinvolved. See the Reset Settings Button documentation for full details. -
The admin sidebar navigation has been overhauled. Extension categories are now collapsible groups with count badges and category icons. Categories start collapsed by default, and searching auto-expands categories with matching results. The active extension's category is pre-expanded on page load. Extensions should declare their category in
composer.jsonunderextra.flarum-extension.category. See the Extension Categories section in the admin docs for the full list of available categories and how to register custom ones. -
All forum pages now use the same page structure through the new
PageStructurecomponent. You should use this component in your extension if you are creating a new forum page. -
A
HeaderDropdowncomponent has been added which is used for theNotificationsDropdownandFlagsDropdownyour component should extend that instead of theNotificationsDropdown. Along with it has been also added the following components:HeaderListandHeaderListItem. -
A
DetailedDropdownItemhas been added. Checkout theSubsriptionsDropdowncomponent to see how it is used. -
A
Noticescomponent has been added that allows you to easily add global alerts above the hero. -
A
Footercomponent has been added that allows you to easily add content to the footer. -
A
Formcomponent has been added to ensure consistent styling across forms. You should use this component in your extension if you are creating a form. -
An API for frontend gambits has been introduced, checkout the full documentation.
-
A
FormGroupcomponent has been added that allows you to add any supported type of input similar to the admin panel's settings registration. checkout the documentation for more details. -
WelcomeHero.prototype.viewItemshas been moved toWelcomeHero.prototype.bodyItems. -
The frontend
Routesextender has been modified to allow passing a custom route resolver class as the fourth argument when adding routes. -
A
UserPageResolverhas been introduced to allow canonicalizing user slugs if the current URL slug doesn't match. Extensions that add user profile routes should use this resolver to ensure consistent slug canonicalization across the multiple profile routes.
Backend
PHP 8.3
Breaking
- The entire codebase has been updated to use/require PHP 8.3 as a minimum, and with it come more strict types. This is not a breaking change for most extensions. But you should still update your extension's code accordingly and check for any potential issues or deprecated code.
Notable
- A new
Flarum\Locale\TranslatorInterfacehas been introduced, it is recommended to use instead of eitherIlluminate\Contracts\Translation\TranslatororSymfony\Contracts\Translation\TranslatorInterface.
Dependencies
Main packages
Breaking
In composer.json:
- Set
flarum/corepackage requirement to^2.0. - Set other
flarum/*packages to*. - If you have a
phprequirement, make sure it is not below^8.3. - If you have
blomstra/gdpras a requirement, change it to"flarum/gdpr": "*".
wikimedia/less.php (updated from 4.x to 5.x)
Flarum 2.0 upgrades the LESS compiler to less.php 5.x. Most extensions will not need to make any changes to their PHP code, as the breaking changes were handled internally by Flarum core. However, there is one LESS language behaviour change that may affect your stylesheets — see LESS Preprocessing below.
Carbon 3
Breaking
- Flarum 2.0 upgrades Carbon to version 3.
diffInmethods now return floats instead of integers and can return negative values to indicate time direction. This is the most significant breaking change in Carbon 3. If you are using any of these methods, you should update your code to handle floats and negative values.
Other changes can be found in the Carbon 3 change log.
Symfony (updated from 5.x to 7.x)
Notable
- Flarum 2.0 upgrades Symfony components to version 6. Most extensions will not need to make any changes.
Laravel (updated from 8.x to 13.x)
Flarum 2.0 uses Laravel 13 components, depending on your extension you may need to adapt your code. Here are some notable highlights.
Breaking
- The
$datesproperty on models has been removed. You should now use the$castsproperty instead as such:protected $casts = ['example_at' => 'datetime',]; - When changing columns in migrations, you must always include the entirety of the column definition. For example, if you are changing a nullable column from
stringtotext, you must include the->nullable()method in the new column definition. You will have to update your migrations accordingly. (https://laravel.com/docs/13.x/upgrade#modifying-columns) - The
HasUuidstrait now generates UUIDv7 (ordered) instead of UUIDv4. If your extension uses this trait and relies on UUIDv4, useHasVersion4Uuidsinstead:use Illuminate\Database\Eloquent\Concerns\HasVersion4Uuids as HasUuids; Schema::getTables(),Schema::getViews(), andSchema::getTypes()now return results across all schemas by default. Pass theschemaparameter to limit results to a specific schema.- The
imagevalidation rule no longer allows SVGs by default. To allow SVGs, use'image:allow_svg'.
For more details, see the Laravel 9, Laravel 10, Laravel 11, Laravel 12 and Laravel 13 upgrade guides.
Flysystem (updated from 1.x to 3.x)
Flarum 2.0 upgrades Flysystem to version 3. Most extensions will not need to make any changes, unless you are using/declaring a Flysystem adapter.