What the agent does
The agent clones the repository into its own cloud sandbox and reads the package before choosing a level. In a library like erusev/parsedown, composer.json declares "type": "library", requires php >=7.2 and ext-mbstring, has one dev dependency, phpunit/phpunit ^8.5.52|^9.6.33, and autoloads the Parsedown class with PSR-0 from the repository root; autoload-dev maps TestParsedown, ParsedownTest, CommonMarkTest and CommonMarkTestWeak to test/. The whole library is one file, Parsedown.php, about 52 KB with 69 functions: text(), line(), the setters setBreaksEnabled, setMarkupEscaped, setUrlsLinked, setSafeMode and setStrictMode, a static instance(), and the block and inline handlers registered in the $BlockTypes, $unmarkedBlockTypes and $InlineTypes arrays. phpunit.xml.dist bootstraps vendor/autoload.php and runs test/ParsedownTest.php, a data-provider test over the 128 files in test/data. .gitignore excludes composer.lock and vendor/.
It reads the CI too, because PHPStan's own requirements collide with it. .github/workflows/unit-tests.yaml runs a matrix of PHP 7.2 through 8.4 with shivammathur/setup-php@v2, composer install, vendor/bin/phpunit, and vendor/bin/phpunit test/CommonMarkTestWeak.php || true. Current PHPStan releases need PHP 7.4 or later, so adding it to require-dev would make composer install fail on the 7.2 and 7.3 matrix entries. The agent therefore does not touch composer.json: it adds a separate static-analysis job that uses setup-php's tools: phpstan input to install the PHAR on PHP 8.4 and runs phpstan analyse, leaving the test matrix exactly as it was.
The configuration is phpstan.neon.dist with paths: [Parsedown.php, test], level: 5 as a starting point, phpVersion left at the runtime default, and excludePaths for test/data. The agent runs phpstan analyse in the sandbox and reads every finding before deciding what to do with it. One finding is a real defect it fixes in the pull request: textElements() assigns $this->DefinitionData = array() and blockReference() and inlineLink() read $this->DefinitionData['Reference'], but the class never declares that property, so it is created dynamically, which PHP 8.2 deprecates. The fix is one declared protected $DefinitionData = array(); beside $BlockTypes. Findings that are style rather than bugs, such as array shapes PHPStan cannot infer in the handler methods or mixed parameters in the setters, go into phpstan-baseline.neon through --generate-baseline, so the job passes today and only new code must be clean.
The agent then runs vendor/bin/phpunit to show the fix changes no output, runs phpstan analyse once more to show the baseline leaves zero errors, and tries level: 6 to report in the pull request how many additional findings each higher level would add, without enabling it. It adds a ## Static analysis note to readme.md with the one command contributors run, and nothing else in the readme changes.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add PHPStan to this PHP library. Read composer.json, the source and the CI workflow first. Choose a level you can justify, write a phpstan.neon.dist covering the source and the tests, and generate a baseline for findings that are style rather than bugs. If PHPStan reports something that is a real defect, such as an undeclared property or an impossible condition, fix it and explain it. Add a CI job that runs the analysis; if the package supports PHP versions PHPStan does not run on, install PHPStan only in that job and leave the test matrix and composer.json unchanged. Run the test suite to show behaviour is unchanged. Report how many findings the next level up would add. Open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request on its own branch that adds phpstan.neon.dist and phpstan-baseline.neon, changes .github/workflows/unit-tests.yaml (one new job, the matrix untouched), Parsedown.php (the declared property) and readme.md (one short section). The description quotes the first phpstan analyse output with every finding, says which one was fixed and why it was a bug, lists what went into the baseline by rule, and gives the count for the next level.
The run's record keeps every command with its output: the PHAR installation, each analysis run, the baseline generation and the PHPUnit run before and after the fix, so a reviewer can see the test results did not move.
Before merging, a reviewer checks the chosen level against the team's appetite, reads the baseline to make sure nothing in it hides a real bug, and decides whether the static analysis job should be a required check from the first day or advisory until the baseline shrinks.
Run it on every Linear issue labelled agent
In the console, an automation in the Project that has the repository, with a linear trigger on linear.issue.labeled and config.labels set to agent, starts one run per issue, with the issue text added after the prompt. A ticket that fixes the level or names the paths to analyse reaches the agent as part of that text, and the pull request links the issue.
From your own server, the same work is one POST /o/{org}/sessions with this body and the repository in resources; a webhook on the API key reports run.completed with the session_url to read the pull request link.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Adding static analysis to an existing codebase is a judgment job: which findings are bugs, which are the tool not understanding the code, and how to install the tool without breaking the oldest PHP version the library promises to support. The agent reads the version constraints and the CI matrix before it chooses an approach, and it reads every finding before deciding what to fix and what to baseline.
The sandbox is a real computer with PHP and Composer, so the analysis and the tests run for real and their output stays in the run's record. The pull request shows the findings as PHPStan printed them, with the fix and the baseline side by side. Several libraries can be done at once, each in its own sandbox.
Frequently asked questions
Why not add PHPStan to require-dev?
When the package supports a PHP version PHPStan no longer runs on, a require-dev entry makes composer install fail on that version's CI job. The agent installs the PHAR in a dedicated job instead and says so. If your minimum PHP is recent enough, it adds the dev dependency and uses vendor/bin/phpstan.
What goes in the baseline?
Findings the agent judged to be the analyser not understanding existing code, such as array shapes it cannot infer, grouped by rule in phpstan-baseline.neon. Anything that reads as a bug is fixed instead and explained. The baseline is a list you can shrink over time; the pull request tells you its size.
Which level does it pick?
One it can justify from the findings, high enough to catch undeclared properties and wrong argument counts, low enough that the baseline is not the whole codebase. It reports how many findings the next level adds so you can raise it deliberately. Say a level in the prompt to fix it.
Does it change how my tests run?
No. The test matrix and its commands are untouched; the analysis is a separate job. The agent runs the existing suite in its sandbox to show the one code fix changes no test result.
More PHP jobs
The same job on other stacks
- Add PHPStan to a CodeIgniter 4 Application (CodeIgniter)