Migrating PianoTell to Flarum 2

navindra

I'm creating this thread to track the migration of PianoTell to Flarum 2 with the goal of sharing my experience, hurdles, and hopefully getting some help and guidance along the way!

This is what PianoTell currently looks like on Flarum 1.8.x:

You can already see what I'm up against here. PianoTell doesn't look like a default installation of Flarum because I'm using Flarum Categories. However, Flarum Categories hasn't been updated in over a year, much less updated to support Flarum 2.

Regardless, extensions that change look and feel or even extensions that add certain functionality (like Move Posts) are less worrisome to me than extensions that make and track significant changes in the backend. One such extension that PianoTell uses is Diff for Flarum. Not being able to migrate that data and maintain that functionality in Flarum 2 is kind of a big deal to me.

Following below are the extensions that PianoTell currently has installed.

The ones in Green are the ones that as of now have been ported to Flarum 2 or have replacements. The ones in Blue are likely not crucial for PianoTell and the ones that are ~~crossed out~~ are no longer used. The ones in orange can probably be worked around. The ones in Red are the ones that are critical but not yet ported.

acpl/mobile-tab
antoinefr/flarum-ext-bbcode-fa
askvortsov/flarum-categories
blomstra/fontawesome
clarkwinkelmann/flarum-ext-advanced-search-highlight
clarkwinkelmann/flarum-ext-author-change
clarkwinkelmann/flarum-ext-post-bookmarks
clarkwinkelmann/flarum-ext-post-stream-search
clarkwinkelmann/flarum-ext-shadow-ban
~~clarkwinkelmann/flarum-ext-sudo-mode~~
flarum/approval
flarum/bbcode
flarum/core
flarum/emoji
flarum/flags
flarum/lang-english
flarum/likes
flarum/lock
flarum/markdown
flarum/mentions
~~flarum/nicknames~~
~~flarum/pusher~~
flare/statistics
flarum/sticky
flarum/subscriptions
flarum/suspend
flarum/tags
fof/byobu — Flarum 2 is supposed to have private messages built-in, but I need a migration story.
fof/drafts
fof/formatting
fof/forum-statistics-widget
fof/ignore-users
fof/linguist
fof/links
fof/sitemap
fof/upload
fof/user-bio
fof/user-directory
katosdev/signature
league/flysystem-aws-s3-v3
~~matteocontrini/flarum-imgur-upload~~
migratetoflarum/canonical
~~ralkage/flarum-hcaptcha~~
sycho/flarum-move-posts
sycho/flarum-profile-cover
the-turk/flarum-diff
the-turk/flarum-flamoji — although this will never be ported, Flarum 2 seems to have a beautiful picker! bravo!
the-turk/flarum-stickiest
v17development/flarum-seo

What I’ve done so far:

Spun up a new instance of PianoTell on a dev server.
Consulted https://lab.migratetoflarum.com/ and determined extension upgrade status.

What I plan to do next:

Follow the upgrade instructions here to see how things go.

Feel free to share any feedback or recommendations to make the transition easier.

 Thank you to all Flarum contributors! 👏

huseyinfiliz

navindra I appreciate that you took the risk of upgrading to 2.x on your own. I noticed that some of the developers listed in the extensions you shared haven’t been active in the Flarum ecosystem for quite a while, and they will likely never update their extensions to 2.x.

If you’d like, you can startProposals discussions for such extensions, those you need on 2.x but whose developers are no longer active. If we see that other forum admins also need them, developers like me can take over the maintenance and handle the migration to 2.x.

IanM

navindra

fof/byobu is almost ready for Flarum 2.0
fof/upload will either be updated or it's functionality built into core (dev time dependant)
katodev/signature I will either update on @katos 's behalf, or move to FoF and update
league/flysystem-aws-s3-v3 is not required for Flarum 2.0
the-turk/flarum-diff can be updated quite easily looking at the code.
clarkwinkelmann/flarum-ext-author-change I know @clarkwinkelmann is actively working on his extensions for 2.0 at the moment
clarkwinkelmann/flarum-ext-post-bookmarks - as above

So from your red list, I would not be alarmed. You are in quite a good place ahead of the 2.0 sstable release, which is likely another ₃ - 4 months out yet.

Forogramero

navindra Consulted https://lab.migratetoflarum.com/ and determined extension upgrade status.

Thank you for this tool. My forum was completely vulnerable because I had misconfigured my .htaccess file. On your scale it was marked in red as a D. I was able to fix each of the security issues thanks to this great tool. Truly, thank you!! @clarkwinkelmann . You are great man!

Capybara

huseyinfiliz I appreciate that you took the risk of upgrading to 2.x on your own.

I’m working on this as well, but I’m planning to move to a new forum without upgrading the old one. My community is about 50 people, so it’s easy for me to move everyone over. It seems that, aside from FoF Linguist and the language packs, all the extensions needed to launch a fully functional forum from scratch are already available

navindra

huseyinfiliz Thank you! I'll keep this in mind. From what GreXXL and IanM also mentioned, it seems like things are shaking out but I'm feeling overall very positive now!

GreXXL For the moment testing already ported extensions and creating bugs if there are any on GitHub is what is needed the most.

Just brilliant and thank you for all those insights! I'll hold tight here and focus my experiment on the extensions that are already ported. That was going to be my first step either way.

IanM So from your red list, I would not be alarmed. You are in quite a good place ahead of the 2.0 sstable release, which is likely another 3 - 4 months out yet.

Wow, thanks a ton for that level of detail! I'm feeling a great deal more encouraged now about completing the migration of PianoTell to Flarum 2 in production when things are ready. It's also really great news to hear that Flarum Diff can be easily ported, I was actually thinking that would be the most difficult one.

All in all, some really excellent news. Thank you for that and thanks for all the great work!

Forogramero +1 It's a very clever tool indeed. Definitely takes a lot of insight and imagination to create something like that.

GreXXL

Like mention in different places we strongly advise against upgrading to v2 at this stage. We will still introduce a couple of important changes that will effect some of the extensions not yet made compatible with v2. Also there are plans of moving some of the extensions into to the @FriendsOfFlarum namespace so we can assure their maintenance. For example there are a couple of important extensions by @askvortsov that need this change. Final decisions have yet to be made.

Picking up what @huseyinfiliz said: The Flarum foundation will likely host someBounty to get some extensions moved to @FriendsOfFlarum and updated for v2 so you all can benefit for an easier migration.

For the moment testing already ported extensions and creating bugs if there are any on GitHub is what is needed the most.

huseyinfiliz

GreXXL By the way, what I meant wasn’t that it includes a bounty, but that I’d be able to see other forum admins saying “I need this too.”

In its current state, neither the Flarum extension marketplace nor Packagist can show which extensions are actively being used the most. What I meant was to understand which extensions should be prioritized for migration in 2.x.

IanM

huseyinfiliz What I meant was to understand which extensions should be prioritized for migration in 2.x.

From my perspective, the next two extensions that need working on for 2.x are fof/byobu (potentially complex) and fof/merge-discussions.

huseyinfiliz

IanM When you say migrating Byobu, do you mean creating a tool to migrate it into the existing PM extension on 2.x?

IanM

huseyinfiliz no, flarum/messages is not advanced enough in it's current form to handle the functionality of byobu, so we need to upgrade the existing extension for 2.0 compatibility

navindra

It’s done! I’ve successfully upgraded a dev instance of PianoTell to Flarum 2 minus a lot of extensions.

This is what I started with:

I disabled a bunch of extensions based on my earlier list. I had to disable more after composer failed several times:

acpl/mobile-tab — correction, this one worked
blomstra/fontawesome
fof/linguist

After disabling all the extensions, this is what PianoTell looked like on Flarum 1.8.x (for the sake of comparison):

I also had to change minimum-stability to dev and remove the —no-dev directive. It was also mildly annoying to have to change the driver back and forth between mysql and mariadb.

The first time I tried to run Flarum 2, it failed with this error:

[2025-11-28T02:06:54.574515+00:00] flarum.ERROR: Error: Class "Flarum\Extend\ApiSerializer" not found in /var/www/html/vendor/fof/ignore-users/extend.php:44
Stack trace:
#0 /var/www/html/vendor/flarum/core/src/Extension/Extension.php(304): require()
#1 /var/www/html/vendor/flarum/core/src/Extension/Extension.php(108): Flarum\Extension\Extension->getExtenders()
#2 /var/www/html/vendor/flarum/core/src/Extension/ExtensionManager.php(320): Flarum\Extension\Extension->extend(Object(Flarum\Foundation\Application))
#3 /var/www/html/vendor/flarum/core/src/Extension/ExtensionServiceProvider.php(33): Flarum\Extension\ExtensionManager->extend(Object(Flarum\Foundation\Application))
#4 /var/www/html/vendor/flarum/core/src/Foundation/Application.php(200): Flarum\Extension\ExtensionServiceProvider->Flarum\Extension\{closure}(Object(Flarum\Foundation\Application))
#5 /var/www/html/vendor/flarum/core/src/Foundation/Application.php(163): Flarum\Foundation\Application->fireAppCallbacks(Array)
#6 /var/www/html/vendor/flarum/core/src/Foundation/InstalledSite.php(141): Flarum\Foundation\Application->boot()
#7 /var/www/html/vendor/flarum/core/src/Foundation/InstalledSite.php(74): Flarum\Foundation\InstalledSite->bootLaravel()
#8 /var/www/html/vendor/flarum/core/src/Http/Server.php(58): Flarum\Foundation\InstalledSite->bootApp()
#9 /var/www/html/vendor/flarum/core/src/Http/Server.php(34): Flarum\Http\Server->safelyBootAndGetHandler()
#10 /var/www/html/public/index.php(26): Flarum\Http\Server->listen()

So I also removed:

fof/ignore-users

And with that, everything is working! Flarum 2.x is snappy so far. These are all screenshots from Flarum 2 (compare to earlier screenshots):

fof/formatting works!

I like the new search a lot!

Dark mode doesn’t look good on PianoTell, so I need to figure out how to address that:

All in all, for what’s there, Flarum 2 is looking good! With all the changes, I didn’t expect the transition to be as smooth as it was, although I am missing a lot of extensions currently.

Flarum 2 feels fast and performant. I’ll be playing around some more to see how things are working and see if anything didn’t survive the transition.

Thanks for all the help and advice so far! 🎉

IanM

navindra It’s done! I’ve successfully upgraded a dev instance of PianoTell to Flarum 2 minus a lot of extensions.

Conratulations! 🙂

navindra blomstra/fontawesome

This is now built into core, so no need for the extension anyway 🙂

See https://docs.flarum.org/2.x/themes#fontawesome

navindra

IanM See https://docs.flarum.org/2.x/themes#fontawesome

Thank you! Not quite working for me out of the box.

This is with Font Awesome 6 in prod:

This is Flarum 2:

Things like [fas]circle[/fas] work as expected.

Some small updates on top of that:

acpl/mobile-tab — this actually works fine, I think once I updated minimum-stability it fixed the dependencies
fof/ignore-users — this worked today. if this is you, thanks @IanM!

I couldn't figure out how to fix dark mode based on this:

I don't see any obvious options to tweak as I can only specify 2 colors. I guess I will need to inject some custom CSS?

Continuing to play around here, but as you can see it's only small potatoes so far. 😃

IanM

navindra fof/ignore-users — this worked today. if this is you, thanks @IanM!

Yes, that was me 🙂

If you've not seen it yet, you can follow along the FoF extension upgrade progress here: FriendsOfFlarum

navindra

IanM Oh thanks and nice work!

I'm following that thread now... something about sticky threads makes them easy to overlook sometimes.

navindra

Well, I just installed fof/byobu and it's working great! 🎉

It's really awesome to see all of these up and running:

acpl/mobile-tab
antoinefr/flarum-ext-bbcode-fa
flarum/approval
flarum/bbcode
flarum/core
flarum/emoji
flarum/flags
flarum/lang-english
flarum/likes
flarum/lock
flarum/markdown
flarum/mentions
flare/statistics
flarum/sticky
flarum/subscriptions
flarum/suspend
flarum/tags
fof/drafts
fof/formatting
fof/ignore-users
fof/links
fof/sitemap
fof/user-bio
fof/user-directory
sycho/flarum-move-posts
sycho/flarum-profile-cover
fof/byobu

Not to understate this achievement, but huge kudos to Flarum devs and contributors for all the hard work to get all of that to light up! And it's all working seamlessly as far as I can tell! It's not that hard to imagine that stable release of Flarum 2 is imminent. 👍

These are the remaining extensions from my original list:

the-turk/flarum-diff — I'm assuming this is achievable per IanM's note
askvortsov/flarum-categories — I'm assuming this is achievable
katosdev/signature — I assume this is coming per IanM's note
clarkwinkelmann/flarum-ext-author-change — I assume this is coming
clarkwinkelmann/flarum-ext-post-bookmarks — I assume this is coming
fof/upload — I assume this is coming
fof/linguist — I assume this is coming
v17development/flarum-seo — I'm assuming this is achievable and it's coming
blomstra/fontawesome — should no longer be needed but FontAwesome 6 is not working for me
clarkwinkelmann/flarum-ext-advanced-search-highlight — I assume this is coming
clarkwinkelmann/flarum-ext-post-stream-search — I assume this is coming
clarkwinkelmann/flarum-ext-shadow-ban — I assume this is coming
fof/forum-statistics-widget — I assume this is coming
the-turk/flarum-flamoji — less need for this now
~~league/flysystem-aws-s3-v3~~ — no longer needed per IanM
~~clarkwinkelmann/flarum-ext-sudo-mode~~ — I assume this is coming
~~flarum/nicknames~~ — I am conflicted about the existence of this
~~flarum/pusher~~ — I assume this is coming
~~the-turk/flarum-stickiest~~
~~matteocontrini/flarum-imgur-upload~~
~~migratetoflarum/canonical~~
~~ralkage/flarum-hcaptcha~~

The red ones are the blockers and the top two are the most uncertain ones for PianoTell per my assessment.

@GreXXL mentioned that a couple of @askvortsov's extensions may be upgraded, so there's a chance that Flarum Categories will make the cut:

That leaves the-turk/flarum-diff which is not the top of anyone's priority list but I do assume it's harder to port than askvortsov/flarum-categories (though achievable).

GreXXL

navindra @GreXXL mentioned that a couple of @askvortsov's extensions may be upgraded, so there's a chance that Flarum Categories will make the cut:

Our current focus remains on updating all extensions nevessary to update discuss.flarum.org in order to give Flarum v2 a good rundown before releasing it next year. I cannot make any promises yet that all of Sashas extensions will be moved to the FoF namespace as this also means a lot of maintainance responsibility. Very popular ones like RIch Text, PWA or Categories that are not used on disucss have a higher chance though.

navindra

GreXXL Thank you! That makes sense.

I'll be very excited to see Discuss on Flarum 2. Things are getting real!

I'm taking a crack at updating flarum-diff:

I've forked the-turk/flarum-diff
I applied a few patches from @piwind (the ones I could understand) and tested on Flarum 1.
I ran fl upgrade 2.0 and fl update js-imports and friends.

Results are here:
PrimateCoder/flarum-diff
PrimateCoder:flarum-diff:2.x

There are a few TODOs that have been generated, so I'll follow up on that next before testing.

navindra

navindra There are a few TODOs that have been generated, so I'll follow up on that next before testing.

Yikes, my progress has slowed here.

flarum-diff adds two new serializers which is a concept that is no longer supported in Flarum 1. I apparently need to extend API resources instead.

The doc basically says compare Tags in 1.x vs 2.x and that's not a whole lot for me to go on to understand what needs to be done. A more straightforward example of before/after would have helped.

Continuing to glean the relevant information from the docs... seems I need to go back to basics for a bit.

huseyinfiliz

navindra I was planning to take over the maintenance of this extension. But it's also nice to see that you've already started. If things don’t work out, let me know. I'm considering taking over the maintenance of a few extensions belonging to the-turk as well.