PHPfox to MetaFox Migration: The Complete Technical Guide

After 12+ years building on PHPfox and its successor MetaFox, we have migrated more platforms between these two than any other team we know of. The question we get most often is a version of: "How hard is it really?" The honest answer is that it depends entirely on how much custom code you have — and most people underestimate this.

Why PHPfox and MetaFox are fundamentally different platforms

PHPfox was built on CodeIgniter with Smarty templates. MetaFox is built on Laravel (backend) with React (frontend). These are not incremental differences — they are different languages for the same problem.

In PHPfox, a module consists of controllers (CI-style), models, Smarty templates, language files, and a manifest. In MetaFox, a module consists of Laravel service providers, Eloquent models, REST API controllers, React components, and a JSON manifest. The folder structures, naming conventions, event systems, and data access patterns are completely different.

What the MetaFox importer handles automatically

MetaFox ships with an importer that handles the core data migration from PHPfox. When run correctly, it migrates:

• Users and profiles — including profile fields, avatars, and cover photos
• Friend connections — the social graph carries over
• Posts, photos, videos — core feed content and media attachments
• Groups and pages — with membership relationships
• Private messages — inbox history
• Core platform settings — some admin configuration maps over

The importer is reliable for standard data. We have run it on databases with 200,000+ users without incident. The risk is not in the importer itself — it is in everything it does not cover.

What the importer does not touch

The importer only knows about core PHPfox data structures. Anything that was added by a third-party module or custom development will not be migrated automatically:

• Custom database tables from non-core modules
• Custom profile field data stored outside the standard PHPfox profile table
• Third-party payment records and transaction logs
• Custom subscription or membership data
• Crowdfunding campaign data, backer records, and payout history
• Custom notification preferences
• Any data in tables with non-standard phpfox_ prefixes

Each of these requires a custom migration script — a one-time PHP or SQL process that maps the old schema to the new MetaFox structure, transforming data where necessary.

The custom module rewrite problem

This is where most migrations get expensive and where scope creep happens. Every custom module you built on PHPfox must be rebuilt on MetaFox. The business logic is the same. The code is not.

Here is what a module rewrite involves:

• Laravel backend — new Eloquent models, migrations, service classes, REST API controllers, policies, and event listeners
• React frontend — new components, Redux state integration, API calls, and MetaFox block system registration
• Admin panel — MetaFox's admin uses its own component registry; every admin setting screen must be re-implemented
• MetaFox package structure — modules must conform to MetaFox's package manifest, versioning, and install/uninstall hooks

Realistic timeline breakdown

Here is how we scope a PHPfox to MetaFox migration based on custom module count:

• 0–2 custom modules: 4–6 weeks. Data migration + configuration + testing.
• 3–6 custom modules: 8–12 weeks. Module rebuilds dominate the timeline.
• 7–15 custom modules: 14–20 weeks. Parallel development tracks needed.
• 15+ custom modules: 20+ weeks. Requires full project team and phased delivery.

These estimates assume clean, documented PHPfox code. Undocumented, tightly-coupled modules with no separation between business logic and presentation add 20–40% to any estimate.

The data mapping phase — do not skip it

Before writing a single line of migration code, we document every database table in the PHPfox installation, map it to the corresponding MetaFox structure, and identify transformation requirements. This typically takes 2–3 days but saves weeks later.

The most common mistake we see in failed migrations is skipping this step and running the importer, then discovering mid-project that critical data has no corresponding home in MetaFox.

Testing strategy

We run every PHPfox to MetaFox migration through three environments before production: a development clone for module rebuilds, a staging environment with real production data for migration verification, and a pre-production environment for client acceptance testing. Production data is never used as a development environment.

Row counts are verified before and after every migration script. If the numbers do not match, we do not proceed.

When not to migrate

Not every PHPfox platform should migrate to MetaFox. If your platform has 10+ deeply custom modules, a large active user base, and is generating revenue — the migration risk may outweigh the benefit for the next 2–3 years. PHPfox still works. We still support and extend it.

The decision should be driven by your technical roadmap and your budget, not by a sense that PHPfox is somehow "dead." It is not. It is simply no longer the latest version of the platform.