Download the PHP package ramon/mybb-migrator without Composer

MyBB Migrator (ramon/mybb-migrator)

A faithful, ID-preserving migrator from MyBB (with the DVZ Hash password plugin) to Flarum 2. It is a Flarum extension that ships a suite of php flarum mybb:* console commands. Unlike a generic importer, it keeps the original primary keys (uid -> users.id, tid -> discussions.id, pid -> posts.id, fid -> tags.id, custom gid -> groups.id) so every cross-reference (likes, mentions, quotes, polls, PMs, trader feedback) lands on the right row.

What it migrates:

• Users (IDs preserved) + original passwords kept working (MyBB classic and DVZ Hash / bcrypt), transparently upgraded to Flarum bcrypt on first login.
• Groups (custom groups, IDs preserved) and role mapping (MyBB Admin/Mod -> Flarum Admin/Mod, Banned -> suspended, Awaiting Activation -> unconfirmed e-mail).
• Forums -> Tags (hierarchy preserved) and per-forum view restrictions.
• Threads -> Discussions and Posts -> Posts, with BBCode -> Flarum conversion (s9e), mojibake repair, sticky/locked/soft-deleted flags, and extraction of user/post mentions.
• Likes, Subscriptions, Private Messages (-> fof/byobu), Polls (-> fof/polls), iTrader feedback and Community Reviews (-> huseyinfiliz/traderfeedback), avatars (URL backfill), signatures.

1. Requirements

Target Flarum extensions

These must be installed and enabled before migrating, because the commands write directly into their tables:

About michaelbelgium/mybb-to-flarum

You do not need it at all. This extension has no admin settings page of its own — the MyBB database credentials are supplied via CLI flags and the extension stores them itself (see Configuration below). All data logic lives in this extension's own mybb:* commands.

The companion extension is only useful for copying the physical files (avatars / attachments) into public/assets/..., since this migrator only backfills users.avatar_url and references attachments — it does not move files. If you copy those files manually, you can skip the companion entirely.

Note on settings keys: the credentials are stored under the keys mybb_host, mybb_port, mybb_user, mybb_password, mybb_db, mybb_prefix. These happen to be the same keys the companion extension uses, so if it is installed, filling its admin page is just an alternative way to set the same values. The values are written by this extension's commands regardless — no companion required.

2. Installation

Enable the extension in the Admin panel. Make sure all target extensions above are installed and enabled first.

2.1. Quick start (full command sequence)

Copy-paste, edit the credentials on the first line, and run from the Flarum root (d:\laragon\www\flarum). Only the first command carries the connection flags — every later command reuses them from settings.

Tip — stop on first error. Wrap Phases 1–2 in a loop so a failure halts the whole run (each step depends on the previous one):

Then run the Phase 3 clean-up passes you need (see §4). Linux/macOS users: replace ^/backtick line breaks with \ and run under bash.

3. Configuration (MyBB database connection)

This extension has no admin UI. You point it at the MyBB database entirely through CLI flags. Each command resolves the connection in this priority order:

1. the CLI flag you pass (--host, -u, -p, ...);
2. otherwise the value previously stored in Flarum settings;
3. otherwise a built-in default.

After resolving, it writes the values back to settings — so you pass the flags once (on the very first command) and every later command only needs --force. No settings page, no companion extension required.

Every command shares these options:

In this project the live MyBB tables used the prefix dfsmybb_.

Example (first command sets and stores the connection):

After that, later commands can be run with just --force.

4. Migration order

All write commands require --force. Most support --dry-run to preview. Run from the Flarum root: php flarum <command>.

Recommended order at a glance

The order below is not arbitrary — it is the exact sequence enforced by the ID/foreign-key dependencies between MyBB and Flarum. Run the phases top to bottom.

⚠️ Golden rule: if any command fails, stop and fix it before continuing — each step depends on the previous one. Always back up the Flarum database before you start, and use --dry-run first wherever it is available.

Before you start, confirm:

• [ ] Flarum DB backed up.
• [ ] All target extensions (§1) installed and enabled.
• [ ] php flarum migrate run (creates mybb_legacy_passwords).
• [ ] MyBB DB credentials known (host/port/user/password/db/prefix).

Phase 0 — Preparation

Phase 1 — Core data (order matters — IDs/foreign keys depend on it)

Why this order:

• groups before users — users get attached to custom groups by ID.
• users before content — posts/discussions reference user_id.
• tags before content — discussions are attached to tags (discussion_tag).
• content before likes/mentions/quotes — those reference posts.id / discussions.id, which are only correct because content preserves pid/tid.

Phase 2 — Secondary content (after users + content exist)

Media — remote images & attachments (opt-in, budgeted)

Migrated posts still load their images from wherever they were hosted (imgur, the old domain, a dead image host). These two steps bring the files onto your own server — into public/assets/files, the folder fof/upload's local adapter uses — and repoint the posts at the local copies.

They are outside every guided sequence (Run everything never triggers them): they hit the network and consume disk, so they are always an explicit decision, taken with a limit, after eyeballing a sample.

Nothing here has to be typed in by hand. With the settings still empty, the panel auto-detects on first open (and the commands do the same when run from the CLI):

• which hosts to localize — the posts already migrated are scanned and their image hosts ranked by usage. The busy ones are applied; the long tail is listed on screen marked as left out, never dropped silently.
• where MyBB's uploads folder is — candidates near the Flarum install are probed and each one is proven against real attachname rows before being accepted. A guess that can't be proven is not used.

Scan order: newest discussions first (by discussion id, newest posts first inside each), so a run with a budget localizes what readers open today before it reaches the threads from 2010.

What makes re-running safe:

• Every URL processed is recorded in mybb_migrated_images. Successful ones are re-pointed without touching the network — that is the "skip images already populated" behaviour. Dead ones are remembered as failed and are not retried unless you ask.
• A transient failure is a different thing from a dead image, and is stored as deferred: HTTP 429/5xx, a timeout, a connection reset. Those come back on their own next run — no --retry-failed needed. (Runs from before this distinction existed are reclassified by a migration, so URLs that only ever failed with 429/timeout are queued again.)
• Local filenames are a hash of the source URL, so the same remote image always maps to the same local file; nothing is ever downloaded twice.
• The map is never loaded whole into memory: each page of 200 posts fetches only the rows for the URLs it contains, so a table with a million URLs costs the same RAM as one with a hundred.
• After mybb:rebuild-formatting (which re-derives posts from MyBB and brings the remote URLs back), run php flarum mybb:images --force --relink-only to re-apply the whole map in seconds.

Hosts that do not answer (dead DNS, refused connections) do not stall the scan:

• The first connection failure for a URL sends it to a pending queue instead of burning the inline retries; the scan moves on. When the scan is over, the queue is retried once more with the normal retries/backoff, and the posts whose images came back are rewritten then.
• Two consecutive connection failures on the same host trip it for the rest of the run: every further URL on that host is skipped instantly (no network) and stored as deferred. A domain like s20.postimg.org with 300 images costs two failed connections, not 300 × 6 retries. --no-defer restores the old inline behaviour.
• Hosts that changed URL scheme are rewritten before download. postimg is the known case: http://s20.postimg.org/65kcb53xp/sotd.jpg (2016, dead host) is tried as https://i.postimg.cc/65kcb53xp/sotd.jpg first, the original URL last. Other legacy postimg/postimage hosts (sNN.postimg.cc, .io, postimage.org) follow the same rule; page URLs (/image/<id>/) cannot be translated because they do not carry the file name.
• When a real server answered but the answer was no good — a 404, imgur's removed.png, HTML instead of an image, or a 429 that ended the direct attempts — the same URL is retried through up to three third-party mirrors: DuckDuckGo's image proxy (external-content.duckduckgo.com), the Wayback Machine (web.archive.org, the only one able to serve an image the original host has since deleted) and serveproxy.com. Each is a different host from the original, so a 429 against imgur — or a rate limit against one of the mirrors themselves — does not block the others. The order rotates per image, so the same mirror is not hit first every time. serveproxy.com is skipped for imgur specifically: it re-encodes everything to AVIF, including the removed.png placeholder, in a way that leaves no trace in the response URL — that placeholder is caught by a byte-hash check regardless of which mirror served it. A pure connection failure (dead DNS, refused connection) does not reach the mirrors: that is what the deferred/host-trip handling above already covers, and retrying through a mirror would reuse the same broken network path.

imgur with an API Client-ID (Images tab, or --imgur-client-id):

• Register a free application at https://api.imgur.com/oauth2/addclient and paste the Client-ID. Each imgur image is then resolved with one authenticated call to api.imgur.com/3/image/<id> that returns the right direct link — instead of up to five guesses at i.imgur.com that get rate-limited. A 404 from the API is a definitive failed; downloading the returned link does not count against the API quota.
• The daily cap (default 10000, below imgur's ~12500/day per application) is counted per UTC day and persisted in settings, so it survives across runs and processes; the Images tab shows how much of today's quota is used. Once reached, the remaining imgur URLs are stored as deferred and picked up by a run on the next day. X-RateLimit-ClientRemaining: 0 from imgur ends the day early as well — and that header is also imgur's answer to an unknown Client-ID (HTTP 429), so the console says which of the two it was.
• imgur's API does not answer over IPv6: those calls force IPv4 and skip IPv6 exit interfaces from the rotation.

Dead-image handling worth knowing about:

• Redirects are followed, but the final response is validated: if it is HTML, the file is gone. i.imgur.com/<id>.jpg redirects to the imgur.com/<id> page when the stored object is actually a PNG, so the fetcher retries the other extensions of the same id before giving up.
• imgur's removed.png placeholder is treated as a failure rather than saved as a grey "image removed" tile.
• The MIME type comes from the bytes (finfo / magic numbers), never from the URL extension or the declared Content-Type.

Rate limits and slow hosts

An old forum concentrates hundreds of images on a handful of hosts, so downloading them as fast as possible is the reliable way to earn HTTP 429 in bulk. The fetcher therefore:

• keeps a minimum gap between requests to the same host (--host-delay, 350 ms by default) and a penalty that doubles on every 429 for that host — halved again on each success, so one bad patch does not slow the whole run forever;
• retries transient failures with exponential backoff plus jitter, honouring Retry-After when the server sends it;
• treats --timeout as an idle timeout (cURL low-speed) instead of a hard deadline, so postimg.cc handing over 100 kB in 20 s is no longer killed mid-transfer — and if it does die, the retry resumes with Range: from the bytes already received;
• does not burn the imgur extension variants on a 429. Those .png/.jpeg guesses exist for the "wrong extension" case; firing them at a host that is already refusing us would just quintuple the refused traffic.

Optimization on import (WebP)

Forum images from 2010 are camera JPEGs: 3000 px and 2 MB to be shown at 700 px. Every downloaded image is re-encoded before it is written, which typically removes 80-90 % of the disk it would otherwise take. This is the only cheap moment to do it — afterwards, changing the image format means rewriting the XML of thousands of posts.

• resized so the longest side fits --max-dim (1600 px by default), EXIF orientation applied first so camera photos do not land sideways;
• converted to WebP at --quality (82 by default), transparency preserved;
• without WebP support in GD, the source format is optimized instead (JPEG re-encoded, PNG at maximum compression, BMP promoted to PNG);
• left exactly as downloaded whenever re-encoding would make things worse: animated GIF/WebP, SVG, AVIF, an image bigger than 25 MP, bytes that will not decode, or a result that is not at least 5 % smaller.

The file name carries the real format (mybb-<hash>.webp), and attachments keep their original name with the new extension (holiday.jpg → holiday.webp), so a download never lies about what is inside. Non-image attachments (zip, pdf) are copied byte for byte.

Console language

The output of these steps is what the admin panel's console shows, so it is translated like the rest of the extension — locale/en.yml and locale/pt-BR.yml, under ramon-mybb-migrator.cli. The language is picked, in order, from --locale=xx, the Console output language field on the Connection tab (mybb-migrator.cli_locale), and the forum's default_locale.

If a run ever prints raw keys (ramon-mybb-migrator.cli.…) instead of text, the compiled catalogue under storage/locale is stale — delete that directory's contents (cache:clear does not touch it) and the next run rebuilds it.

Optimizing what is already localized

mybb:optimize-media walks the files already in mybb_migrated_images and re-encodes them with the same rules — for forums migrated before optimization existed, or downloaded with --no-optimize. Per file, in this order, so a post never points at a file that is gone:

1. the new file is written (the old one is still there);
2. the fof_upload_files row is repointed, base name included;
3. the posts are rewritten — a literal replace of the file name inside the XML, which covers the <IMG src> and the [img] token in one pass;
4. the map row is updated;
5. only then is the old file deleted (--keep-old skips this).

Files stored outside the document root (restricted tags) are re-encoded on their own side and stay there. --dry-run reports the whole balance without writing anything; --kind=image|attachment and --limit=N narrow the run.

Three sweeps, each repointing a different place — the map (fof_upload_files + posts), files on disk with no map row, and avatars (users.avatar_url), which are usually the biggest pile of leftover JPEGs in a migrated forum. Avatar @2x/@3x variants change format together with their base file or not at all, because the core derives their path from it.

Restricted tags: files are written outside the document root, not moved later

public/assets/files is served by the web server without PHP ever running, so while a file sits there no permission of any kind applies to it. For a forum imported with restricted tags that matters: the images of a private area would be readable by anyone holding the URL.

ramon/dfs solves this by keeping tag-scoped uploads in storage/dfs-private-uploads and serving them through a permission-checked route. This extension does not reimplement any of that — it just makes sure the bytes never land on the wrong side to begin with:

• before writing, the discussion is checked with Flarum's own Discussion::whereVisibleTo(new Guest()) — the same call ramon/dfs makes, not a second reading of the tag rows;
• if a guest cannot see it, the file is written straight into the private store and registered in dfs_private_uploads;
• at the end of the step, every touched file is handed to ramon/dfs for reclassification, which is what settles the case of one image appearing in both an open and a restricted discussion (its rule is the least restrictive one).

Without ramon/dfs installed all of this switches off and files are written publicly, which is the only possible destination in that case.

Choosing where that private store actually lives (--private-dir=PATH, or the "Private uploads folder" field on the Images tab, only shown when ramon/dfs is detected): storage/dfs-private-uploads is a hardcoded constant in ramon/dfs's own code, not a setting — it has to be exactly there for the gated route to find the files. So instead of writing somewhere else, this extension turns that path into a symlink pointing at the folder you chose — handy when the forum's storage disk is small, or you'd rather keep these files on a separate volume or backup schedule. ramon/dfs keeps reading from storage/dfs-private-uploads exactly as before and never notices the difference. On Windows, creating a directory symlink needs Developer Mode or an elevated process; when that's not available, nothing is shelled out to work around it — the run tells you the exact mklink /J command to run by hand in an elevated prompt instead. Nothing here is destructive: a folder that already exists at the canonical path with files in it is left untouched and the run just says why linking was skipped, rather than moving production data around on its own.

The URL frozen into the post is /assets/files/… either way — that is precisely what GatePrivateUploads looks for when it rewrites a render to the gated route. Only the location of the bytes differs.

fof/upload is optional: without it the files are still downloaded and the posts do point at the local copies — they just won't appear in the media manager. With it installed, each file is also registered in fof_upload_files and linked to its post. The insert is schema-introspective, so it works across fof/upload versions (which have moved columns around several times).

Attachments are appended to the end of the post — the [attachment=N] tokens were dropped during content migration, and MyBB itself renders non-inlined attachments at the bottom. The post is rewritten through unparse → text → parse, the same path Flarum uses when a post is edited, so the resulting XML is always valid.

All of this is also driven from the Images & attachments tab of the extension's admin page. The tab opens with the URLs to localize and the uploads folder already filled in by auto-detection, and adds a "Localize this discussion" box: paste a discussion URL and only its images are fetched. Both steps run detached in the background, reporting a live progress bar — a real percentage when the total is cheap to know (a single discussion, the attachment table), and an indeterminate bar with the running count otherwise. Counting 273k posts up front just to draw a percentage would cost more than the work itself, so the bar says "unknown" instead of inventing one.

Phase 3 — Content clean-up / fidelity passes (run as needed)

These are idempotent fix-up passes over already-migrated content. They were created to repair specific artifacts found in this forum's data (Tapatalk emoji, mojibake, literal BBCode that didn't parse, quote/mention styling, signatures). Run only the ones you need; safe to re-run.

Do not run them all blindly. They are specific to your dataset and some are opposites of each other (e.g. restore-quote-mentions ↔ revert-quote-mentions, fix-quotes ↔ compact-quotes) — running everything would undo itself. Migrate Phases 1–2 first, look at the live forum, then apply only the passes you actually need. The most commonly needed ones are fix-charset, fix-smilies, fix-emojis, normalize-bbcode, fix-user-mentions and fix-signatures.

About mybb:rebuild-formatting. Because it re-reads each affected post from the MyBB source and re-parses it, it overwrites posts.content and therefore drops any earlier Phase-3 edits on those posts (smilies, mentions, quote styling, strike/spoiler reverts). After running it, re-run the idempotent Phase-3 passes you use — typically fix-smilies, fix-quotes (or your chosen quote-style pass), fix-user-mentions, fix-mention-slugs, and any revert-md-strike-sub / revert-ispoiler — to restore them. The converter itself is now fixed, so a fresh mybb:content migration no longer produces these markdown artifacts in the first place.

Helpers / diagnostics

5. How passwords keep working

MyBB stores either the classic hash md5(md5(salt) . md5(password)) or, with the DVZ Hash plugin, a bcrypt hash ($2y$..., sometimes bcrypt over the classic md5).

1. mybb:users copies each original hash/salt/algorithm into the companion table mybb_legacy_passwords (created by this extension's migration).
2. A custom Flarum password checker (mybb-legacy, see src/Auth/MybbPasswordChecker.php) intercepts logins:
   • if a legacy row exists, it verifies the password the MyBB way (src/Support/MybbPassword.php);
   • on success it re-hashes to Flarum bcrypt, saves, and deletes the legacy row — so each user is upgraded transparently on first login.

No password resets, no e-mails — users log in with their existing credentials.

6. Architecture

Design notes:

• Reads MyBB with a buffered cursor for small sets and an unbuffered cursor (MybbDatabase::cursor()) for large tables to keep memory flat.
• Writes in batches (200–2000 rows) with FOREIGN_KEY_CHECKS=0 around bulk inserts.
• mybb:content self-cleans the Flarum content tables before re-importing, so it can be re-run safely.
• The admin panel paints from a cheap status call (~10 ms) and loads the source/target counts afterwards: those are COUNT(*) over large InnoDB tables (~13 s on the reference forum) and used to hold the whole page hostage. They are cached for mybb-migrator.counts_ttl seconds (default 300) and recomputed on demand — automatically once a step finishes, or via the Recount button.

7. Caveats

• The fix-up passes in Phase 3 are data-specific: they target artifacts seen in this particular forum (Tapatalk, DVZ Hash, double-UTF-8 mojibake). Review each before running on a different dataset; always try --dry-run first where available, and back up the Flarum DB.
• Avatar files are not copied by this extension (mybb:avatars only points users.avatar_url at files you already placed in public/assets/avatars). Post images and attachments are handled — see the media section above — but only when you run those steps explicitly, with a budget.
• mybb:wipe is destructive (clears Flarum content). It keeps schema, core groups and settings, but use it only on a throw-away/staging install.

8. License

MIT.