Onboarding to an unfamiliar PHP repository means building a working mental model without reading every file, and Atlas starts from meaning rather than filenames. Ask a plain-language question and the semantic index returns ranked snippets with real paths. Run glob on the top-level directories and the Composer layout appears in one call: the source tree the autoload block maps, the tests directory, the vendor tree Composer installed, and the phpunit.xml that says how the suite runs. Heavy fan-out goes to the explore subagent, which is permissioned read-only so it cannot change anything while it looks around, and findings land in a todowrite list.
How do I build a mental model of a PHP repo without reading every file?
Start with a question, not a file. Atlas's codebase_search takes a plain-language question, for example how requests are authenticated, queries the semantic index, and returns ranked snippets with file paths, so 3 deliberate reads replace an afternoon of following a front controller through routing and middleware by hand.
The instinct on day one of a PHP project is to open the entry point and trace execution outward. In a mature Composer application that path runs through a router, a middleware stack, a service container, and several layers of abstraction before it reaches anything that resembles business logic. Atlas skips the trace. Run atlas in a project with a composer.json, ask about the behavior you care about, and let the ranked snippets tell you where to look. Atlas reads your namespaces, autoload config, and dependencies, so the PSR-4 mapping in composer.json is understood as a mapping and not as decorative JSON.
What does glob reveal about a Composer project's layout?
Atlas runs glob on the top-level directories to see the package layout and naming conventions before opening anything. In a Composer project, 1 glob call exposes the whole shape: the source directory the autoload block maps, the tests directory, the config directory, and the vendor tree Composer installed.
Directory shape is information in PHP. An autoload section that maps a namespace prefix to a source directory, paired with an autoload-dev section mapping a test namespace elsewhere, tells you exactly where production code stops and test code begins. Three files answer most of a newcomer's questions, so find them early: composer.json for dependencies and autoloading, phpunit.xml or phpunit.xml.dist for how the suite is configured, and the PHP-CS-Fixer configuration for what the project considers correctly formatted. Running glob before any read makes every subsequent read purposeful.
How does the explore subagent survey a PHP codebase safely?
Atlas delegates wide sweeps through the task tool to the explore subagent, which carries a deny-by-default permission set allowing only 6 tools: grep, glob, read, bash, webfetch, and websearch. Surveying every namespace in an unfamiliar PHP application therefore has no path to modify a single file.
Exploration is expensive in tokens and cheap in risk, which is precisely the profile that suits delegation. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so a broad sweep of a large Composer monorepo does not consume the context you need for the actual conversation. The read-only guarantee is enforced rather than requested: the permission set denies by default and allows only the inspection tools. Handing a client's PHP repository to a subagent that literally cannot write to it is a different proposition from trusting an instruction not to.
How do I learn what a PHP project's tests already guarantee?
Run PHPUnit. In an unfamiliar PHP codebase the suite is the most honest documentation available, because the assertions describe behavior the maintainers were willing to defend, and phpunit.xml tells you which suites exist and which directories they cover before you run anything. PSR-12 formatting through PHP-CS-Fixer keeps the diff readable afterward.
Comments drift and README files age, but a passing PHPUnit assertion is a claim someone is still standing behind. Run the suite early so you know the baseline: which suites are green, which are skipped, and how long the whole thing takes. Composer resolves the dependencies from composer.json, so what runs locally is what CI runs. Reading a handful of test cases also teaches you the project's idioms faster than reading the production code does, because a test shows the intended usage of a class rather than its internals.
How do I keep onboarding notes from evaporating between sessions?
Atlas records what you learned as a todowrite list so the open questions survive into the next turn. After a first pass through a PHP application, that list usually holds 4 or 5 entries: which namespace owns authentication, whether PHP-CS-Fixer runs in CI, which vendor packages are load-bearing, and which suites are red.
Onboarding produces knowledge and it produces gaps, and only one of the two survives a night's sleep unless you write it down. A todowrite list keeps the gaps alive and specific, pairing each open question with the artifact that would answer it. That habit turns day two into a continuation instead of a restart. When onboarding finally turns into a first change, Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so your opening pull request on a codebase you barely know is reviewed by you before it is reviewed by anyone else.
Step by step
- 01Run atlas in a project with a composer.json so the PHP namespaces, autoload config, and dependencies are all in scope.
- 02Ask codebase_search a plain-language question, for example how requests are authenticated; it queries the semantic index and returns ranked snippets with file paths.
- 03Run glob on the top-level directories to see the Composer package layout and naming conventions, including the source tree, the tests tree, and the vendor directory, before opening anything.
- 04Read the two or three files codebase_search ranked highest, then follow imports with the lsp tool's goToDefinition operation instead of resolving PSR-4 paths by hand.
- 05Delegate wide sweeps to the explore subagent through the task tool; it is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch.
- 06Open phpunit.xml to see which suites exist, then run PHPUnit to learn what behavior the project already guarantees.
- 07Read the PHP-CS-Fixer configuration so your first diff matches the project's PSR-12 style instead of fighting it.
- 08Record what you learned as a todowrite list so the open questions about the PHP codebase survive into the next turn.
Frequently asked questions
- how to understand a legacy php codebase quickly
- Run Atlas where composer.json lives, ask codebase_search a plain-language question about the behavior you care about, and run glob on the top-level directories to see the layout before opening files.
- can an ai agent explore my php repo without editing anything
- Yes. Atlas's explore subagent is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch, so it cannot modify a file while it surveys the project.
- what should i read first in an unfamiliar php project
- composer.json for dependencies and autoloading, phpunit.xml for how the suite is configured, and the PHP-CS-Fixer configuration for the house style. Those three answer most of a newcomer's questions.
- does atlas run phpunit on a project it has never seen
- Atlas can run PHPUnit and read the result. The assertions are the most honest description of what the codebase guarantees, and they teach the project's idioms faster than the production code does.
- how do i keep notes from an onboarding session with an ai coding agent
- Atlas records findings as a todowrite list, so open questions such as which vendor packages are load-bearing survive into the next turn instead of being lost when the session ends.
- how does atlas handle psr-4 autoloading
- Atlas reads your namespaces, autoload config, and dependencies from composer.json, so the PSR-4 prefix mapping is understood as a mapping and imports resolve to real directories.
- can subagents run in parallel while i keep working
- Yes. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so a wide sweep of a large Composer monorepo does not consume your main context.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Onboard to an Unfamiliar Codebase with Atlas in 2026
How to onboard to an unfamiliar codebase with Atlas in 2026: use codebase_search, glob, read, lsp, task, and todowrite to build a mental model fast.
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.
Rename a Symbol Across the Repo in PHP With Atlas (2026)
Rename a PHP class, method, or constant everywhere it is used. Atlas pairs the lsp tool's findReferences with grep and an edit tool that refuses ambiguous replacements.
Extract a shared helper from duplicated code in PHP with Atlas (2026)
The same PHP logic is copy-pasted in 5 controllers with different variable names. Atlas finds it by meaning with codebase_search, extracts one helper, and proves it with PHPUnit.
Self-review your working diff before committing in PHP with Atlas in 2026
Catch your own mistakes in PHP code before they reach a reviewer or CI. Atlas helps PHP developers in 2026 self-review uncommitted diffs, run PHPUnit tests, and apply PHP-CS-Fixer formatting.
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.
Plan a multi-file change before editing in PHP with Atlas (2026)
Design a multi-file PHP change before any edit lands. Atlas's plan agent denies edit outside .atlas/plans/*.md, and plan_exit gates the handoff to the build agent.
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.