Flarum Importer

Moves a Flarum 1.x forum (MySQL/MariaDB or SQLite) into FlatBB: members, groups, tags, discussions, posts, likes,
attachments and read marks. It also imports only the members into a forum that keeps its content
(--members-only). Post bodies are stored by Flarum as s9e TextFormatter XML; this plugin converts them to
FlatBB Markdown (paragraphs, headings, emphasis, quotes, spoilers, lists, tables, code, links, pictures, mentions,
fof/upload attachments) instead of stripping the tags. The old addresses keep working through redirects.

The importer plugs into FlatBB's own import job: Admin → Import → Flarum, or the php flatbb import flarum
command. Every step is batched and the job can be left and resumed; progress and the report live in Admin → Import.

What comes over

Flarum	FlatBB
Groups	Member groups. The Admin group maps to FlatBB's administrators, Moderator/Member to the built-in groups; every other group is created and its permissions in restricted tags become category permissions.
Users	Accounts, matching by email. Passwords keep their bcrypt/argon hash, so members sign in with their old password. `nickname` becomes the display name; suspensions become bans; avatars stored on this server are copied.
Tags	A primary tag becomes a category, every other tag becomes a normal tag. Hidden tags stay hidden; restricted tags become category permissions (view/reply/post groups); child tags intersect their parent's audience.
Discussions	Topics with their author, date, view count, pin and lock state. Hidden discussions are imported as deleted. The old topic id is preserved.
Posts	Markdown bodies, reply links, edit dates, the author and the IP address. Unapproved posts are imported for review; private posts are skipped.
Likes	Post likes.
Read marks	Each member's last-read position per topic.
fof/upload	Pictures become images and other files become links. Files under the Flarum directory are copied into FlatBB's uploads; external URLs stay remote.

Old addresses redirect: /d/{id}-{slug} to the topic, /d/{id}-{slug}/{number} to that post, and /t/{slug} to the
category or tag with that slug.

Using it

Back up the target forum. The import replaces the starter content: topics, posts, categories, tags and the
members' imported data. On a second import it also removes every member except the administrator. (Not with
--members-only, which leaves the forum as it is.)
Install and enable this plugin (php flatbb plugin:sync, php flatbb plugin:enable flarum_importer).
Open Admin → Import → Flarum and fill in the source database, or run the CLI:

php flatbb import flarum --config=/var/www/flarum/config.php
php flatbb import flarum --driver=mysql --host=127.0.0.1 --port=3306 --database=flarum \
    --user=flarum --password-file=/root/.flarum-db --prefix= --root=/var/www/flarum --url=https://old.example
php flatbb import flarum --driver=sqlite --path=/var/www/flarum/database.sqlite --root=/var/www/flarum

--config reads the database settings from a Flarum config.php. For the explicit fields the password comes from
--password-file, else FLARUM_DB_PASSWORD, else --password (visible in the process list, so prefer the other two).
--root is the Flarum directory; without it, avatars and attachments stored on this server cannot be copied.
--url turns relative links in old posts into absolute ones.

Continue the job from Admin → Import or with php flatbb import flarum when the CLI session ended early.

Importing only members

Add accounts to a forum that already has content and members, without removing anything:

php flatbb import flarum --config=/var/www/flarum/config.php --members-only

Only the Groups and Members phases run: no categories, topics, posts, files or read marks are read. A source account
whose email (ignoring case) or username already exists on this forum is skipped and left exactly as it is; the
report says how many were kept. In this mode Flarum's Admin and Moderator groups do not become this forum's staff
groups (such members keep a custom group if they have one, otherwise they are regular members). Avatars, bios,
passwords, join dates and suspensions come over as usual.

The password

The database password is never written to plugin settings, the job log or the import report:

In the admin page, Check the source writes the connection to a 0600 file under data/ for up to 15 minutes;
Start the import reads that file once and deletes it. The job then keeps the password only in its own secret
field (the core's job storage) for the lifetime of the job.
The CLI reads the password from a file, the environment or an interactive-free argument, as above, and passes it to
the job the same way.

Limits

Flarum 2 stores bodies in a newer XML format. The scan warns, and bodies may come over as plain text.
Private discussions and private posts are skipped: FlatBB has no private topics. The report counts them.
FlatBB gives a topic one category, so extra primary tags beyond the first are dropped (and reported).
Read marks are approximated to the last-read post number; exact per-post read state is not stored by FlatBB.
Only files on the same server can be copied; attachments hosted elsewhere keep their original URL.
The redirect tables live in this plugin's tables. Disabling or uninstalling the plugin stops the redirects
(uninstall drops the tables; the imported content stays).

Requirements

FlatBB 0.2.0+, PHP 8.1 with pdo_mysql (or pdo_sqlite) and dom/libxml for the post converter. Flarum 1.x with
the Tags, Likes and fof/upload extensions when you want those imported; the scan reports which ones are missing.