Evolve Doctor: Is Your PHP Application Ready to Modernize?

Modernizing a PHP application is not only a code problem.

You can clean up classes, separate modules, introduce better boundaries, and design a migration plan—and still hit a wall because the environment underneath the application is not what you expected.

The PHP version may be wrong.

An extension may be missing.

A required directory may not be writable.

A configuration value may not exist.

Or the machine running the application may simply not satisfy the assumptions your modernization plan depends on.

That is the problem Evolve Doctor is designed to help expose.

Audit tells you what you have. Doctor helps you verify the environment you are about to run it in.

---

The Problem: “It Works on This Server” Is Not Enough

Legacy PHP applications often accumulate environmental assumptions over time.

Maybe the original developer knew that:

• a certain PHP extension had to be installed,
• a directory had to be writable,
• a specific environment variable existed,
• or PHP had to be above a particular version.

Years later, those assumptions may exist only in the production server.

Then modernization begins.

A developer creates a new environment, deploys part of the application somewhere else, introduces a sidecar, moves a capability into a new service, or prepares for a newer runtime.

Suddenly:

Production
    works

New environment
    fails

And the failure may have nothing to do with the business logic itself.

This is why environment verification deserves its own tool.

---

What Evolve Doctor Does

Evolve Doctor is part of the EvolvePHP Core tooling.

Its job is deliberately narrower than Audit.

Doctor runs explicit checks against the runtime or project environment and produces structured findings.

The current foundation includes checks for things such as:

• PHP version requirements,
• PHP extensions,
• Composer-declared extension requirements,
• required environment variables,
• writable paths.

A host application chooses which checks to compose.

That is important.

EvolvePHP does not try to magically inspect everything on the machine and declare:

“Your application is ready.”

Instead, applications define the conditions that matter, and Doctor evaluates them.

---

A Small Example

In the current EvolvePHP source-preview application skeleton, Doctor is exposed through the application CLI:

php bin/evolve doctor

The default skeleton currently wires the checks needed for its own basic runtime:

• PHP version;
• Composer-required PHP extensions.

The underlying Doctor foundation can also be composed with additional checks when an application needs them.

Conceptually:

DoctorRunner
    |
    +-- PHP version check
    +-- extension check
    +-- Composer requirement check
    +-- environment variable check
    +-- writable path check

Each check contributes findings rather than hiding the reasoning behind one giant “healthy/unhealthy” result.

That makes the result useful during modernization because you can see what assumption failed.

---

Why Not Put This Inside Audit?

Because they answer different questions.

Evolve Audit

Audit treats a target PHP application as data.

It can inspect things such as:

• Composer metadata,
• lockfile evidence,
• source structure,
• direct global/state coupling,
• selected runtime-hazard patterns.

It does not need to bootstrap the target application.

Evolve Doctor

Doctor evaluates explicit assumptions about the environment in which software is expected to run.

Think of it this way:

Audit
"What does this application appear to contain?"

Doctor
"Does this environment satisfy the conditions we expect?"

Using both gives you better evidence than trying to stretch one tool into both jobs.

---

Why This Matters During Modernization

Consider a legacy system that depends on an extension that has always been installed on its existing server.

Nobody remembers it is required.

An assessment of the source may reveal the application structure, dependencies, globals, and coupling.

But when you prepare a new runtime for an extracted capability, the missing extension becomes the actual blocker.

Doctor lets you make those requirements explicit.

That becomes particularly useful when moving from:

One long-lived server

toward environments such as:

development
staging
CI
containers
workers
sidecars
new application hosts

The more environments you introduce, the less safe undocumented machine assumptions become.

---

Doctor Is Not a Modernization Certification Tool

This boundary matters.

A clean Doctor report does not mean:

✓ the application architecture is good
✓ the code is safe for persistent workers
✓ the application can be migrated automatically
✓ dependencies are vulnerability-free
✓ the database can be moved safely
✓ the application is production-ready
✓ modernization will succeed

Doctor checks the conditions represented by the checks you actually configured.

Nothing more.

For example, a directory can be writable while the application still has serious architectural problems.

PHP can satisfy the required version while the code still relies heavily on global mutable state.

All configured extensions can exist while a migration strategy is still unsafe.

That separation is intentional.

---

Where Doctor Fits in the Bigger Modernization Flow

A useful modernization process needs several different kinds of evidence.

In EvolvePHP, the direction looks more like:

Legacy PHP Application
        |
        v
      Audit
        |
        |  What exists?
        |  Where is the coupling?
        |  What deserves investigation?
        v
      Doctor
        |
        |  Does the target environment
        |  satisfy explicit requirements?
        v
  Adoption Planning
        |
        |  What capability moves?
        |  Who owns routes and data?
        |  What is the rollback path?
        v
      Bridge
        |
        |  Integrate incrementally
        |  without rewriting everything
        v
Incremental Modernization

Each layer has a different responsibility.

That is much safer than creating one command that claims to “analyze and modernize your PHP application.”

---

The Architectural Idea

Doctor follows one of the core design principles behind EvolvePHP:

Make important assumptions explicit.

If an application requires something, represent that requirement.

If it can be checked, check it.

If it cannot be proven, do not pretend it has been proven.

That applies whether the application is being built from scratch or has been running for ten years.

Modernization becomes easier when the environment is no longer a collection of undocumented assumptions.

---

Where Evolve Doctor Is Today

EvolvePHP 2 is still pre-release, and Doctor is part of that evolving foundation.

The current implementation is intentionally bounded.

It provides the mechanisms for explicit environment checks, but it is not trying to become:

• a vulnerability scanner,
• a full infrastructure auditor,
• a production-readiness certification service,
• or an automatic migration engine.

Those boundaries are important because useful diagnostics need to be trustworthy.

A tool should tell you what it actually knows—not what would sound impressive in a report.