# Add PHPStan Static Analysis to a PHP Library

Yes. An agent adds PHPStan to your PHP library with a config, a baseline for today's findings and a CI job, fixes what is clearly a bug, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/add-phpstan/php/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Fix `Call to undefined function create_function()` after moving to PHP 8](https://getrush.ai/run/fix-create-function-removed/php/)
- [Fix "Deprecated: Creation of dynamic property is deprecated" in PHP 8.2](https://getrush.ai/run/fix-creation-of-dynamic-property-deprecated/php/)
- [Fix `Call to undefined function each()` on PHP 8](https://getrush.ai/run/fix-each-function-removed/php/)

## The same job on other stacks

- [Add PHPStan to a CodeIgniter 4 Application](https://getrush.ai/run/add-phpstan/codeigniter/)

## More jobs like this: Turn a Linear label into a PR

- [Persist Pinia State in a Vue App from a Linear Issue](https://getrush.ai/run/add-pinia-persistence/vue/)
- [Add Pod Disruption Budgets to Kubernetes Manifests from a Linear Issue](https://getrush.ai/run/add-pod-disruption-budgets/kubernetes/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
