how to plan a multi-file php refactor before an AI agent edits anything

Use Atlas's plan agent. Its permission set denies edit for "*" and allows writes only under .atlas/plans/*.md, so Atlas researches your namespaces and PHPUnit suite with codebase_search, grep, read, and the lsp tool, and writes the design into a plan markdown. No .php file changes until you approve plan_exit.

what is plan_exit in atlas and how do i decline it

plan_exit ends plan mode. It asks "Plan at is complete. Would you like to switch to the build agent and start implementing?" Answering No raises Question.RejectedError and keeps you in plan mode refining the PHP plan. Answering Yes hands off to the build agent, which can edit files and run Composer, PHPUnit, and PHP-CS-Fixer.

how does atlas find every implementation of a php interface

Atlas walks the symbol graph with the lsp tool, which surfaces implementations and callers that a grep for the interface name would miss, including methods supplied by a trait. codebase_search covers the case where you know the behavior but not the class name.

does atlas read composer.json and the psr-4 autoload map

Yes. Atlas's documented PHP setup is to run atlas in a project with a composer.json and let it read your namespaces, autoload config, and dependencies. The autoload map is ground truth for how a PHP namespace resolves to a file path under src/.

will atlas run phpunit after implementing a planned change

The build agent can, once plan_exit has handed off. PHPUnit is the test runner in Atlas's documented PHP toolchain, alongside Composer as the package manager and PHP-CS-Fixer as the formatter. The plan agent itself cannot run edits at all.

how do i review each php file before atlas writes it

Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each change to a class in src/ or a case in tests/ is a patch you approve. Atlas also snapshots file changes as git patches, so an approved edit can still be rolled back.

can atlas apply psr-12 formatting to a php codebase

PHP-CS-Fixer is the formatter in Atlas's documented PHP toolchain, and the documented setup is to ask Atlas to add PHPUnit tests or apply PSR-12 formatting, reviewing the diff. Formatting runs from the build agent, not from plan mode.

Plan a multi-file change before editing in PHP with Atlas (2026)

A multi-file PHP change goes wrong when the design happens while the edits are already landing. Atlas separates the two. Atlas's plan agent is described as "Plan mode. Disallows all edit tools." Its permission set denies edit for "*" and allows writing only under .atlas/plans/*.md, so Atlas can read your composer.json, follow your PSR-4 autoload map into src/, and cross-reference the PHPUnit suite in tests/, without any of that research turning into an edit. When the design is written, the plan_exit tool asks whether to switch to the build agent and start implementing. Answer Yes and the build agent takes over, able to run Composer, PHPUnit, and PHP-CS-Fixer. Answer No and Atlas raises Question.RejectedError, leaving you in plan mode with the PHP source still untouched.

What is Atlas plan mode and what can it do in a PHP project?

Atlas plan mode is an agent whose description is literally Plan mode. Disallows all edit tools. In a PHP repo with a composer.json it can read every namespace in src/, every PHPUnit case in tests/, and the autoload map, while its permission set denies edit for every path except the 1 allowed location, .atlas/plans/*.md.

Plan mode is a permission configuration, not a prompt instruction, which is why it holds. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and the plan agent's rules deny edit for "*" with a single exception for the plan markdown. A PHP change that spans a controller in src/Http/, a service in src/Domain/, a migration, and four PHPUnit cases is exactly the kind of change where a half-finished design becomes half-finished edits. Plan mode makes that structurally impossible: the design phase cannot write a .php file even if the model decides it would like to.

How does Atlas research a PHP codebase without permission to edit it?

Four Atlas tools stay allowed inside plan mode: codebase_search, grep, read, and the lsp tool. For PHP, that covers the whole research job, tracing a class through its PSR-4 namespace, finding every implementation of an interface, and reading how the PHPUnit suite currently pins the behavior you intend to change.

PHP's autoloading means a class's file path is derived from its namespace, and Composer's autoload map in composer.json is the ground truth for that mapping. Atlas reads it. codebase_search then answers the questions where you know the behavior but not the class name: Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so a query about how invoices are totaled finds the right service class even if it is called something else. grep confirms the exact class or method name. The lsp tool walks the symbol graph, which matters in PHP where a method may come from a trait rather than the class body.

Where does the PHP change plan get written, and why only there?

Atlas writes the plan into .atlas/plans/*.md, the 1 path plan mode is permitted to write. That constraint is what makes plan mode trustworthy: the plan markdown is the only artifact a PHP planning session can produce, so no src/ file and no phpunit.xml can be quietly modified along the way.

The plan markdown is the deliverable and the boundary at once. A useful PHP plan enumerates the concrete surface of the change: which namespaces under src/ gain or lose classes, which interfaces change signature and therefore which implementations must follow, which PHPUnit cases in tests/ pin the current behavior and will need updating, and whether Composer needs a new package. Because Atlas computes a unified diff for every file edit and surfaces it for approval before writing, the plan is the first of two reviews, and the per-file diff during implementation is the second.

What does plan_exit ask, and what happens if you say No?

Atlas's plan_exit tool asks Plan at <path> is complete. Would you like to switch to the build agent and start implementing? There are 2 answers. Yes hands the PHP work to Atlas's build agent, and No raises Question.RejectedError, returning you to plan mode with the plan still open and src/ still untouched.

plan_exit is routed through Atlas's question tool, so the handoff is a decision you make rather than a transition that happens to you. The No path is not an error state in the colloquial sense: Question.RejectedError is the mechanism by which a plan you are not happy with stays a plan. You keep researching with codebase_search and grep, keep refining the markdown, and call plan_exit again when the design holds up. Only Yes puts an agent with edit permissions in front of your PHP source.

What can Atlas's build agent do to a PHP codebase that plan mode cannot?

The build agent is the only Atlas agent that can edit .php files. Once plan_exit hands off, the build agent applies the multi-file change, runs Composer for any new package, runs the PHPUnit suite, and runs PHP-CS-Fixer for PSR-12 formatting, with a unified diff surfaced for approval on every file it writes.

The build agent inherits the plan and executes it, but not without review. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each change to a class in src/ and each new PHPUnit case in tests/ is a patch you approve. Atlas snapshots file changes as git patches, so a multi-file PHP refactor that goes sideways can be diffed and rolled back rather than untangled by hand. Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf once PHPUnit is green and PHP-CS-Fixer is clean.

Step by step

01Run atlas in a PHP project that has a composer.json, so Atlas can read your namespaces, autoload config, and dependencies.
02Switch to Atlas's plan agent, whose permissions deny edit for "*" and allow it only under .atlas/plans/*.md, so no .php file under src/ can change while you design.
03Research with codebase_search when you know the behavior but not the class name, and with grep when you know the exact namespace or method to confirm.
04Walk the PHP symbol graph with the lsp tool to find every implementation of a changing interface, including methods that arrive through a trait rather than the class body.
05Write the design into the plan markdown under .atlas/plans/, listing each namespace under src/ that changes, each PHPUnit case in tests/ that must be updated, and any Composer package the change requires.
06Call plan_exit, which asks "Plan at <path> is complete. Would you like to switch to the build agent and start implementing?"
07Answer No to keep refining, which raises Question.RejectedError and leaves you in plan mode; answer Yes to hand the PHP change to the build agent.
08Review the unified diff Atlas surfaces for every .php file the build agent writes, then have it run PHPUnit for the suite and PHP-CS-Fixer for PSR-12 formatting.

Frequently asked questions

how to plan a multi-file php refactor before an AI agent edits anything: Use Atlas's plan agent. Its permission set denies edit for "*" and allows writes only under .atlas/plans/*.md, so Atlas researches your namespaces and PHPUnit suite with codebase_search, grep, read, and the lsp tool, and writes the design into a plan markdown. No .php file changes until you approve plan_exit.
can atlas modify src/ files while it is planning a php change: No. The Atlas plan agent is described as "Plan mode. Disallows all edit tools." Every tool call is permission-gated against allow, ask, and deny rules before it runs, and plan mode's deny rule covers every path except .atlas/plans/*.md, so a class under src/ cannot be written.
what is plan_exit in atlas and how do i decline it: plan_exit ends plan mode. It asks "Plan at <path> is complete. Would you like to switch to the build agent and start implementing?" Answering No raises Question.RejectedError and keeps you in plan mode refining the PHP plan. Answering Yes hands off to the build agent, which can edit files and run Composer, PHPUnit, and PHP-CS-Fixer.
how does atlas find every implementation of a php interface: Atlas walks the symbol graph with the lsp tool, which surfaces implementations and callers that a grep for the interface name would miss, including methods supplied by a trait. codebase_search covers the case where you know the behavior but not the class name.
does atlas read composer.json and the psr-4 autoload map: Yes. Atlas's documented PHP setup is to run atlas in a project with a composer.json and let it read your namespaces, autoload config, and dependencies. The autoload map is ground truth for how a PHP namespace resolves to a file path under src/.
will atlas run phpunit after implementing a planned change: The build agent can, once plan_exit has handed off. PHPUnit is the test runner in Atlas's documented PHP toolchain, alongside Composer as the package manager and PHP-CS-Fixer as the formatter. The plan agent itself cannot run edits at all.
how do i review each php file before atlas writes it: Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each change to a class in src/ or a case in tests/ is a patch you approve. Atlas also snapshots file changes as git patches, so an approved edit can still be rolled back.
can atlas apply psr-12 formatting to a php codebase: PHP-CS-Fixer is the formatter in Atlas's documented PHP toolchain, and the documented setup is to ask Atlas to add PHPUnit tests or apply PSR-12 formatting, reviewing the diff. Formatting runs from the build agent, not from plan mode.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Plan a Multi-File Change Before Editing with Atlas in 2026

How to plan a multi-file change with Atlas in 2026: the plan agent denies all edit tools, you research with codebase_search and lsp, then plan_exit hands off.

Atlas for PHP in 2026

Atlas, the terminal-native AI coding agent, empowers PHP developers in 2026 with intelligent code understanding, secure workflows, and direct integration for Composer and PSR standards.

Add a regression test for a bug fix in PHP with Atlas (2026)

Add a PHP regression test for a bug fix in 2026: Atlas proves the PHPUnit test fails red first, applies the fix with edit, and re-runs the same command to prove green.

Review a Pull Request in PHP with Atlas in 2026

Streamline your PHP pull request reviews in 2026 with Atlas, the terminal-native AI agent. Leverage PHPUnit, Composer, and PHP-CS-Fixer for thorough, context-aware code analysis, catching bugs a line-by-line read would

Document a PHP Module with a README in 2026

Atlas helps PHP developers in 2026 generate accurate README documentation directly from source code. It leverages Composer, PHPUnit, and PSR standards to describe what your PHP code actually does today.

Onboard to an Unfamiliar PHP Codebase with Atlas (2026)

Build a mental model of an unfamiliar PHP repo in 2026 without reading every file. Atlas maps the Composer layout, delegates sweeps to a read-only explore subagent.

Migrate a Deprecated API Across Every Callsite in PHP with Atlas in 2026

Move your PHP codebase off deprecated functions or modules onto replacements without missing a single caller. Atlas integrates with Composer and PHPUnit for a verified migration.

Research a third-party API before integrating it in PHP with Atlas (2026)

Research a third-party API before writing PHP in 2026: Atlas uses websearch and webfetch behind permission prompts, then writes the client and PHPUnit tests.

Browse this resource hub