Inherited a Broken PHP Platform? Here Is How to Fix It

20% of our work is platform rescue. We have inherited platforms that were 70% built and abandoned, platforms that had a working live version destroyed by a botched update, and platforms where the previous developer left with the passwords. The scenarios are varied. The approach is consistent.

This is the process we follow every time we take on a broken or abandoned PHP platform. Not because we invented it — because we learned from every failure of not following it.

Before you touch anything: make a complete backup

This sounds obvious. It is repeatedly not done. Before any engineer looks at any code with any intention of changing anything, a complete backup must exist:

• Full file backup of the web root (including hidden files, .htaccess, .env)
• Full database backup (dump, not just an export of some tables)
• Test that the restore works on a separate environment

If the platform is live and broken, there is data being written to it right now. The backup you just made is the last known-good state. Everything else builds from here.

Phase 1: Read before you write

The first engineering session on an inherited codebase should be entirely read-only. No code changes. The goal is understanding:

• Error logs first — PHP error log, web server error log, and application-specific logs. These tell you what is actively failing and often give you the file and line number where failures originate.
• Database schema — read the schema, not just the code. The database is the ground truth for what the application does. Tables named cf_campaigns, affiliate_referrals, kyc_documents tell you what was being built even if the code is incomplete.
• Configuration files — config.php, .env, and any platform-specific configuration. Understand what services are configured, what API keys exist, what is pointing to where.
• Codebase structure — identify which files are platform core (do not touch) versus custom additions (where the work is). On SocialEngine this is clear; on a heavily customised WordPress, less so.
• Recent Git history (if it exists) — the last 10–20 commits often tell the story of what was being worked on and where it stopped.

Phase 2: Classify what is broken

Before fixing anything, classify every broken item:

• Critical — blocking users: login broken, payment processing down, core navigation inaccessible. Fix these first.
• Critical — security: open admin access, known vulnerable PHP version, malware. Fix immediately regardless of timeline.
• Significant — features not working: a payment module that throws errors, a form that does not submit, notifications that are not sending.
• Incomplete — features that were started but never finished: database tables with columns that code does not use yet, half-implemented modules, commented-out functionality.
• Technical debt — things that work but are wrong: security vulnerabilities in working code, unscalable queries, hardcoded credentials.

This classification drives the roadmap. Critical issues get fixed in the first sprint. Incomplete features get scoped and quoted. Technical debt goes on a separate list for after stabilisation.

The most common failure modes we see

1. PHP version incompatibility

A hosting provider upgraded PHP from 7.4 to 8.1, and code that relied on deprecated functions started throwing fatal errors. This is the most common single cause of "site suddenly broke" rescues. The fix is identifying deprecated function usage and updating it — on SocialEngine and Magento in particular, this is well-documented territory.

2. Plugin or extension conflict

A plugin or module was installed or updated, and it conflicts with another installed component. The symptoms: white screen (fatal error suppressed), 500 error, broken admin. The diagnosis: disable recently changed extensions until the culprit is identified, then fix the conflict.

3. Database migration half-run

A migration script ran but failed partway through, leaving the database in an inconsistent state — some tables updated, some not. The symptoms are often subtle: features that work for some users but not others, data that appears then disappears. Fixing requires understanding what the migration intended to do, verifying the current state row by row, and completing or reversing it cleanly.

4. Abandoned mid-development

The most complex rescue scenario: a platform that was being built and the developer stopped, leaving it in an indeterminate state. Some features are complete. Some are half-implemented. Some exist only as database tables with no corresponding UI. The approach is always: stabilise the working features, document the incomplete ones, scope completion work, and never try to "finish" features before understanding them completely.

What you should not do with an inherited platform

• Do not start rewriting immediately. The urge to "clean this up" before fixing it leads to fixing bugs that did not exist while introducing new ones. Stabilise first. Rewrite later, if at all.
• Do not delete files you do not recognise. Unknown files in web roots are often either malware (which should be removed carefully, not blindly) or legitimate custom work with no documentation.
• Do not upgrade the platform version immediately. A Magento or WordPress upgrade on a broken platform adds new variables to an already unknown situation. Stabilise on the current version, then upgrade.
• Do not trust that the backup you found is the complete backup. Always make a new one before you start.

When rescue is not the right answer

Sometimes a codebase is too far gone to rescue economically. The signals:

• The custom code is so tightly coupled to the platform that even minor fixes require understanding the entire application
• The security vulnerabilities are architectural, not incidental
• The cost to complete the incomplete features exceeds the cost of starting from scratch with the lessons learned

We will tell you if this is the case. We have walked away from rescue scopes that would have cost the client more than a rebuild. The honest assessment upfront is worth more than a long rescue engagement that ends in a rebuild anyway.