Insights:PHP Legacy Code: What to Do First When Taking Over an Old Project
Six Things You Need to Gather First
| Item | What to Confirm | What to Do If Missing |
|---|---|---|
| Code | Complete source code, version records, uncommitted changes | Take a read-only backup first; do not modify directly on production |
| Environment | PHP version, extensions, web server, dependencies | Recreate a working local environment |
| Database | Table schemas, account privileges, data volume, backups | Export structures and sample data first, confirm backups are restorable |
| Configuration | Domain, URL rewriting, cache, queues, cron jobs | Record each item in detail; don't rely on memory |
| Permissions | Admin panel accounts, server accounts, third-party keys | Establish least-privilege access and a handover checklist |
| Requirements | What to change, what not to change, acceptance criteria | Write a one-page change description before quoting |
Miss even one of these, and custom development turns into "guessing while fixing".
Week 1: Audit Only, No Feature Development Yet
1. Get the Project Running
Document the PHP version, extensions, Composer dependencies, database connections, cache, and queue setup. Many legacy projects aren't broken by code—they fail because environments are inconsistent: PHP 8.4 locally but still 7.4 on production, missing extensions, etc.
2. Locate Entry Points and Routing
Start with index.php, the public entry point, config files, routing definitions, template directories, and the database layer. Whether it's a custom MVC or a framework project, draw out the request flow:
Domain → Entry Point → Router → Controller → Service/Model → Template → Output
Not knowing how requests flow through the system, it's easy to accidentally modify shared logic when changing a single page.
3. Examine the Actual Database Structure
Don't rely solely on field names in the code. Export the table schema and confirm:
- Primary keys, indexes, and unique constraints.
- Soft deletes, status fields, and timestamp fields.
- Which tables are legacy leftovers and which are still actively written to.
- Whether any triggers, views, or scheduled tasks directly mutate data.
4. Perform a Restorable Backup
Back up everything: code, database, upload directories, config files, certificates, and scheduled tasks. A backup isn't just copying files—it means confirming you can restore them in a test environment. Without a recovery drill, a backup is only psychological comfort.
5. Check for Obvious Risks First
Common risks in legacy projects:
- SQL string concatenation, weak admin passwords, unrestricted file uploads.
- Error pages exposing paths; secrets hardcoded into source.
- No role-based access control in the admin panel; former employees' accounts still active.
- Missing logs—when things break, you're left guessing.
These don't all have to be fixed this round, but flag them before quoting: clarify what's in scope and what requires a separate security remediation effort.
Define Change Boundaries Next
Categorize requests into three groups:
- Bug fixes: Existing functionality doesn't match expectations—reproduce, locate, then fix.
- Modifying existing flows: Involves pages, APIs, databases, and permissions—always document the impact scope clearly.
- New modules: Quote these as new-feature work; don't underrate them with "while I'm at it" pricing.
Secondary-development quotes usually depend on:
- Code readability and coupling level.
- Whether historical data compatibility is required.
- Involvement of payments, authentication, permissions, or file storage.
- Need for server migration or domain changes.
- Whether additional testing and documentation are needed.
Minimum Deliverables at Handover
- Running code and deployment instructions.
- Database change scripts and rollback plan.
- New configuration items and third-party account list.
- Test accounts, test steps, and known limitations.
- List of files modified in this change.
"Change until satisfied" is not an acceptance criterion. Acceptance criteria should be reproducible functional points, boundary conditions, and regression scope.
When Not to Take the Job
- No source code available; only compiled output can be modified.
- No database backup exists, nor is backup permitted beforehand.
- Production environment lacks a testing environment; direct live changes are requested.
- The requester cannot confirm an acceptance owner and has no defined change boundaries.
- The project involves third-party systems or data with clear authorization issues.
In these situations, taking over and remediating risks first is far more prudent than jumping straight into feature work.
One-Sentence Rule
The first step in PHP secondary development isn't writing code—it's bringing the legacy project to a state that is "runnable, backing up-capable, roll-backable, and debuggable." If that foundation isn't solid, every new feature only amplifies risk.
Related Reading: