There are three ways to inherit a codebase: your company acquired one, you took over as the technical lead, or the agency that built it has gone away. In all three you are given a system, a set of expectations, and roughly a month before someone senior wants a view.
The temptation is to start reading code. Do not. Code quality is one of the least predictive things you can assess in the first week, and it is the easiest to form an unfair opinion about. This is the order we work in.
One rule before you start: change nothing in week one. Not a dependency, not a config value, not a composer update. You cannot tell what is load-bearing yet, and an outage you caused destroys your credibility to report on the ones you did not.
Week 1: Can You Even Run It?
Everything else is speculation until you have the system running on a machine you control.
- Get a local environment working from a clean checkout, and time how long it takes. This number is the single best proxy for how expensive every future change will be. Two hours is healthy; two weeks tells you most of what you need to know.
- Inventory the environments. Production, staging, and the two servers nobody mentioned. Find them by reading DNS and the cloud account, not by asking.
- Establish what runs where — web servers, workers, cron, queues, scheduled reports, webhook receivers. The undocumented cron job is the classic landmine.
- Confirm you have the accounts. Domain registrar, DNS, hosting, cloud, repositories, CI, error tracking, payment gateways, email delivery. Missing access is a commercial problem to escalate on day two, not week four.
- Verify the backups exist and restore. Untested backups are a rumour. Restore one to a scratch environment and look at it.
- Find out who knows things. Often one person, sometimes at a company that no longer employs them. This is your most perishable asset — book time with them immediately.
Week 2: Risk, Not Quality
Now measure exposure. These are the findings that change decisions and get budget approved.
- PHP version, per environment, against the official support timeline. An unsupported version is the finding that outranks everything else in this list.
- Dependency age and vulnerability status. Run an audit against the lock file. Count how many majors behind the framework is — that number, not the code style, tells you what an upgrade will cost.
- Abandoned dependencies. Packages with no release in years, or forks pointing at a personal repository. Each is a project you have inherited without knowing it.
- Secrets in the repository. Look through the whole history, not just the current tree. Assume anything found is compromised.
- How data is protected. Where personal data lives, who can read it, what is encrypted, and what your obligations are for it.
- Whether deployment is repeatable. A system that deploys by someone editing files on the server has no reliable rollback, which shapes every risk assessment after it.
Write findings as risks with a likelihood, an impact and a cost to fix — never as complaints about the previous team. The audience for this document is commercial, and this code is bad is not actionable while we are 14 months from unpatched is.
Week 3: Now Read the Code
With context established, code assessment becomes useful rather than judgemental. Look for structure and testability rather than style.
- Run static analysis at a low level and record the baseline. You are not fixing it; you are measuring it. The trend over the next year is what matters.
- Check test coverage where it counts — checkout, payment, pricing, anything touching money. Overall percentage is a poor metric; coverage of the dangerous paths is the real one.
- Find the business logic. In a healthy codebase it is in identifiable places. In an unhealthy one it is spread through controllers, templates and a stored procedure nobody knew about.
- Look for the god objects — the class every feature touches. It will tell you where change is most expensive and where the next incident will come from.
- Read the git history for churn. Files changed most often are where the business actually operates, and where investment pays back fastest.
- Identify the untouchable. Every legacy system has a module nobody will modify. Find out what it is and why.
The bus factor deserves its own note. If one person can explain the order pipeline and nobody else can, that is a higher risk than any code smell you will find, and the mitigation — pairing, documentation, a second person who genuinely knows it — needs to start immediately rather than after the assessment.
Week 4: Score It and Recommend
Score each dimension 1 (healthy) to 5 (critical), and let the total drive the recommendation rather than your instinct.
- Security and version currency — the only dimension that can force a decision on its own
- Dependency health — how far behind, how much is abandoned
- Operability — can you deploy, roll back, observe and restore?
- Testability — could you change the pricing logic and know whether you broke it?
- Comprehensibility — how long until a new engineer is productive?
- Business fit — does it still do what the business needs, or is it fighting the roadmap?
Then place it:
- Mostly 1–2: maintain and improve. The system is fine. Fix the specific findings and get on with the roadmap.
- Mostly 2–3: invest deliberately. A funded remediation programme — version upgrade, dependency governance, tests on the money paths — running alongside normal delivery.
- Mostly 3–4: incremental replacement. Strangler fig, replacing the system route by route while it keeps running. We describe that pattern in detail in migrating a legacy PHP monolith to Laravel.
- Mostly 4–5, or business fit is 5: rebuild. Rare, and it should feel unavoidable rather than appealing. A rebuild justified by code quality alone is usually a rebuild that will be regretted.
Be suspicious of your own instinct to rebuild. Almost every engineer inheriting an unfamiliar codebase wants to. Almost none of the resulting projects deliver what was promised in the time that was promised. Require the score to justify it.
What to Hand Over
The output is one document, readable by someone non-technical, containing:
- A one-page summary with the recommendation and its three supporting reasons
- A risk register — each finding with likelihood, impact and cost to fix, ordered by urgency
- The version and dependency position, with the dates support ends
- A 90-day plan for the things that should not wait, costed
- The access and ownership gaps, which are usually commercial rather than technical
- An honest statement of what you could not assess and what it would take to find out
That last item is what distinguishes a professional assessment from a confident one. A month is not enough to know everything, and saying so is more credible than pretending otherwise.
We run this assessment for clients through our custom PHP practice and our PHP development team — often before an acquisition closes, occasionally after an agency relationship has ended badly. The related question of whether the language itself is the problem is covered in is PHP still the right choice for eCommerce.
Frequently asked questions
How long should a legacy code assessment take?
Four weeks of part-time effort is enough to produce a defensible recommendation for most mid-size systems. Less than two weeks produces an opinion rather than an assessment; more than six usually means someone is trying to fix things rather than measure them.
What is the first thing to check?
Whether you can get it running locally from a clean checkout, and how long that takes. That single number predicts the cost of every future change better than any code-quality metric, and it is available on day one.
Should we rebuild or refactor an inherited PHP system?
Refactor or replace incrementally in almost every case. Rebuild only when the business fit has genuinely failed — the system no longer does what the business needs — rather than when the code is unpleasant. A rebuild justified by code quality alone is usually regretted.
What is the biggest risk in an inherited codebase?
Usually not the code. It is an unsupported PHP version, missing access to a domain or cloud account, untested backups, or one person being the only one who understands a critical subsystem. Those are the findings that change decisions.
How do we present the findings to non-technical stakeholders?
As a risk register: each finding with a likelihood, a business impact and a cost to fix, ordered by urgency. Never as criticism of the previous team — that reads as positioning and it makes the whole document easier to dismiss.
Get a Second Opinion
If you have inherited something and need an independent read before you commit a budget to it, we will run the assessment and hand you the document. Talk to our team; we reply within a business day.