Untangle the Web: A phpBB Admin's Guide to Mapping Extension Dependencies Before They Wreck Your Forum

You've been running your phpBB forum for years. You've installed mods when you needed them, upgraded a few, left others alone because hey — if it ain't broke, right? Then one afternoon you update a single extension and suddenly your forum's sidebar is gone, your points system stops tracking, and three other mods throw PHP errors you've never seen before.

Welcome to dependency hell. Population: you.

This isn't a rare edge case. It's one of the most common pain points for US-based phpBB admins running mid-to-large community forums, and it's almost entirely preventable. The fix isn't glamorous — it's documentation, mapping, and a little patience before you click that upgrade button. Let's break it down.

Why Extension Dependencies Are a Hidden Minefield

phpBB's extension system is genuinely well-designed. Extensions declare their requirements in [composer.json](https://en.wikipedia.org/wiki/Composer_(software)), which means phpBB theoretically knows what each mod needs. But in practice, things get messy fast.

Here's why:

• Shared libraries get updated independently. If two of your mods both rely on a shared phpBB library or a third-party vendor package, updating one mod can quietly shift that shared dependency to a version the other mod wasn't built for.
• Legacy mods don't always play by the rules. Older extensions — especially anything ported from phpBB 3.0-era MODs — may have dependencies baked into their code without properly declaring them in composer.json.
• Admin-installed workarounds create invisible links. If you ever manually edited a mod's files to get it working with another, you've created a dependency that lives nowhere except your memory (and maybe a sticky note on your monitor).

The result is an ecosystem where mods are quietly leaning on each other in ways that aren't obvious until something breaks.

Step 1: Build Your Extension Inventory

Before you can map dependencies, you need a clean list of everything installed. Head to your Admin Control Panel and pull up the full extension list. Don't just screenshot it — actually document it in a spreadsheet or a simple text file.

For each extension, capture:

• Extension name and vendor
• Version currently installed
• Last updated date (check the phpBB.com extension DB or the mod's own repository)
• Whether it's enabled or disabled
• Any notes about manual modifications you've made

This inventory becomes your baseline. You'd be surprised how many admins discover they have extensions installed that nobody remembers enabling.

Step 2: Read Every composer.json Like It's a Contract

Every properly built phpBB 3.1+ extension includes a composer.json file in its root directory. This file lists the extension's explicit requirements. Navigate to /ext/vendor/extensionname/composer.json for each mod and look at the require block.

You're looking for two things:

1. phpBB version requirements — Does this mod require a minimum phpBB version? A maximum?
2. Other extension dependencies — Some mods explicitly require other extensions to be present and active.

Copy these requirements into your spreadsheet. Start building a picture of what requires what. Even a basic two-column list — "Extension" and "Requires" — gives you more visibility than most admins ever have.

Step 3: Draw the Dependency Map (Seriously, Draw It)

This sounds old-school, but visual mapping is genuinely the fastest way to spot problems. Tools like draw.io (free, browser-based) or even a whiteboard work fine.

Create a node for each extension. Draw arrows from dependent mods to the mods or libraries they rely on. When you're done, you'll likely see a few patterns:

• Hub nodes — Extensions that multiple other mods depend on. These are your highest-risk components. Updating or removing a hub node without checking everything pointing to it is how forums blow up.
• Orphan nodes — Extensions with no dependencies and nothing depending on them. These are your safest candidates for removal or independent updates.
• Chains — Mod A requires Mod B which requires Library C. A change anywhere in that chain ripples forward.

Real-world example: A gaming community forum in the Midwest was running a popular points/rewards extension alongside a custom shop mod and a tournament bracket tool. When they updated the points extension, the shop mod broke immediately — it had been calling a function from the points extension that was renamed in the new version. Nobody had documented the connection because it wasn't declared in composer.json; it was a loose integration the original developer had set up manually. Two hours of downtime and a very unhappy community later, they had their first dependency map.

Step 4: Create a Dependency Change Log

Going forward, every time you install, update, or remove an extension, log it. Keep a simple running document — even a Google Doc works — with:

• Date of change
• What you changed
• Why you changed it
• Any dependencies affected
• Post-change status (did everything still work?)

This log becomes invaluable when something breaks six months later and you're trying to figure out what changed. It also helps if you ever hand admin duties off to someone else.

Step 5: Safe Removal and Upgrade Protocol

Armed with your dependency map, here's a practical protocol for making changes without triggering cascades:

Before upgrading any extension:

1. Check your map — is anything else depending on this mod?
2. Review the extension's changelog for breaking changes or renamed functions.
3. Spin up a staging environment if you can (even a local XAMPP install works).
4. Back up your database and files. Every time. No exceptions.
5. Upgrade in staging first, test all dependent mods manually.
6. Only then push to production.

Before removing any extension:

1. Check your map for anything pointing to this mod.
2. Disable the extension first (don't uninstall immediately) and monitor for 24–48 hours.
3. Check your forum's error logs during that window.
4. If everything's clean, proceed with uninstall.

Real-world example: A hobbyist forum focused on amateur radio had accumulated 22 extensions over five years. When they tried to remove an old arcade mod, they discovered a custom leaderboard extension had been pulling user data from the arcade mod's database tables. Removing the arcade mod without checking first would have thrown fatal errors across the leaderboard pages. The dependency map they built (after the fact, unfortunately) would have caught this in about ten minutes.

The Template You Actually Need

Here's a simple dependency map template you can copy into any spreadsheet:

Extension Name	Vendor	Version	Requires	Required By	Hub?	Safe to Update Alone?
Points System	acme	2.3.1	phpBB 3.3+	Shop Mod, Leaderboard	Yes	No
Shop Mod	acme	1.8.0	Points System	None	No	No
Leaderboard	xyzdev	1.1.2	Points System	None	No	No

Fill this out for your entire extension list and you've got a working dependency map in under an hour.

Don't Wait for the Fire

Most admins only start caring about dependency mapping after something breaks. By then, you're already in triage mode — debugging under pressure, dealing with user complaints, and trying to remember what you changed three weeks ago.

Building the map before a crisis costs you maybe two or three hours of focused work. That's a trade-off that pays for itself the first time you avoid a multi-hour outage. Your forum's community deserves better than crossed fingers and hope. Give them a properly documented extension ecosystem instead.