# Upgrade PHPUnit in a PHP Library Without Dropping Old PHP Versions

Yes. An agent widens your library's PHPUnit constraint to 10 and 11, makes the tests run on every version, proves it on each PHP release you support, and opens a PR.

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

## What the agent does

The agent starts from the constraint and the matrix, because together they say what the upgrade is allowed to break. In a library like erusev/parsedown, `composer.json` requires `php >=7.2` and `phpunit/phpunit ^8.5.52|^9.6.33`, `.github/workflows/unit-tests.yaml` tests PHP 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3 and 8.4, and `composer.lock` is in `.gitignore`, so each job resolves the newest PHPUnit its PHP allows. PHPUnit's own `composer.json` files set the floors: 10.5 needs PHP 8.1, 11.5 needs 8.2 and 12 needs 8.3. A library that keeps 7.2 therefore cannot replace the constraint; it can only extend it to `^8.5.52|^9.6.33|^10.5|^11.5`, and the work is making one set of test files run on all four lines.

It then reads the tests for what the newer lines reject. `test/ParsedownTest.php` overrides the constructor as `final function __construct($name = null, array $data = array(), $dataName = '')`, fills `$this->dirs` from `initDirs()` there, and passes three arguments to the parent; PHPUnit 10.5 declares `__construct(string $name)` and 11.5 tags it `@final`. Its data provider `data()` is an instance method that loops over `$this->dirs`, and `CommonMarkTestStrict::data()` is an instance method that calls `$this->fail()` when the specification cannot be downloaded; PHPUnit 10 deprecated instance providers and 11 requires static ones, which run before any test object exists. Both test methods are bound to their providers with `@dataProvider` annotations in doc comments. `phpunit.xml.dist` is two attributes, `bootstrap` and `colors`, and one suite naming one file, so there is no coverage or logging section to migrate.

The edits follow from that reading. The constructor override goes away; `initDirs()` and `data()` become static, the parser is created in `setUp(): void`, and the CommonMark provider reports a failed download with the static `self::fail()`. A static provider is valid on every PHPUnit line in the constraint, so nothing forks by version. `initDirs()` and `initParsedown()` are protected hooks that a subclass can override, and making one of them static changes that contract, so the pull request names it as the one change an extension's test suite would notice. The agent keeps the annotations where the oldest line needs them and decides from PHPUnit's own output, not from memory, whether to add attributes beside them.

Proof is a run per PHP version. In its sandbox the agent installs each PHP release the matrix names that it can obtain, runs `composer update` to see which PHPUnit resolves there, runs `vendor/bin/phpunit` with deprecations displayed, and records the pair and the result. It runs `vendor/bin/phpunit test/CommonMarkTestWeak.php` separately, as the workflow does with `|| true`, and compares its failure list before and after so a provider change that silently stops generating cases would show. Any matrix entry it could not run locally is named, with the workflow left to cover it on the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Upgrade PHPUnit in this PHP library so the newest PHP versions in the CI matrix run PHPUnit 10 or 11, without dropping any PHP version the library supports. Read composer.json, phpunit.xml.dist, .github/workflows/unit-tests.yaml, .gitignore and every PHP file under test/ first, and check the PHP requirement of each PHPUnit line in its own composer.json. Extend the phpunit/phpunit constraint rather than replacing it. Remove the test constructor override, make the data providers and what they call static, create the parser in setUp, and report a failed specification download with a static call. Keep one set of test files that runs on every PHPUnit line in the constraint. For each PHP version in the matrix that you can install in your sandbox, run composer update, record which PHPUnit resolved, run vendor/bin/phpunit with deprecations displayed and keep the output; run test/CommonMarkTestWeak.php separately and compare its case count and failures before and after. Do not change Parsedown.php. Open a pull request with a table of PHP version, PHPUnit version and result, every deprecation PHPUnit printed, and any change to a protected test hook that a subclass could notice.",
  "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

A pull request that changes one line of `composer.json` and the files under `test/`, and leaves `Parsedown.php` and `phpunit.xml.dist` as they are unless a run shows the configuration needs a line. The description carries a table with one row per PHP version: the PHPUnit release Composer chose, the test and assertion counts PHPUnit printed, and any deprecation notice, quoted. It lists the CommonMark run's failures before and after, and the matrix entries the workflow has to confirm because the sandbox could not.

A reviewer checks that the oldest row still resolves PHPUnit 8.5 and passes, that the newest rows show a 10 or 11 release with no deprecation left, and that the note about the static hooks is acceptable for any package that extends these test classes. Because there is no lock file, merging changes nothing for users of the library; it changes what CI installs on its next run.

## Run it on every Monday morning

Create an automation in the Project with a `schedule` trigger set to Monday in the team's time zone and a prompt that asks for the development dependencies with a newer major line than the constraint allows, the PHP floor of each, and which matrix entries could take it. With `read_only` on, the run reads and comments and never pushes. The upgrade itself starts when someone sends this body to `POST /o/{org}/sessions` with the repository in `resources`.

For a group of libraries, a script on your own server sends the body once per repository, each with a `request_id` that is a UUID v5 of the repository name and the week, so a retried call returns the run it already started. Runs past the key's `max_concurrent` are created `queued` and start as slots free, so the script needs no retry loop.

## Why run it on Rush?

A test-framework upgrade across eight PHP versions is a grid, and the usual way to fill it in is to push and wait for CI, one failure at a time. The agent fills in the grid in its own sandbox before it opens the pull request, with each `composer update` and each PHPUnit run kept in the run's record, so the reviewer sees which pairs were executed and what each printed.

The same request suits a library on a narrower range, where the answer may be to drop PHPUnit 8 and 9 outright, or one whose configuration file has coverage and logging sections that PHPUnit's migration command has to rewrite. Each run reads that project's constraint, matrix and tests and proposes the smallest change that leaves every supported PHP version green.

## Frequently asked questions

### Why not just require PHPUnit 11?

PHPUnit 11.5 needs PHP 8.2, and this library's `composer.json` still accepts PHP 7.2 and tests on it. Requiring 11 alone would make `composer install` fail on five of the eight matrix entries. Extending the constraint lets each PHP version install the newest PHPUnit it can run.

### Do static data providers work on PHPUnit 8 and 9?

Yes. Static providers are accepted on every line; what changed is that PHPUnit 10 deprecated instance providers and 11 stopped supporting them. Making them static is the one form that runs everywhere in the constraint, which is why the agent does not fork the tests by version.

### Will the run replace @dataProvider annotations with attributes?

Not by default, since PHPUnit 8 and 9 only read the annotations. The agent runs the suite on the newest line with deprecations displayed and reports what PHPUnit says about doc-comment metadata. If a notice appears, it adds attributes beside the annotations and shows that the oldest line still passes.

### Does this change the library itself?

No. The request forbids edits to `Parsedown.php`, and the diff is the development constraint and the test files. If a test fails on a newer PHP for a reason inside the parser, the pull request reports it as a finding instead of patching it.

## More PHP jobs

- [Add Mutation Testing to a PHP Library with Infection](https://getrush.ai/run/add-mutation-testing/php/)
- [Add PHPStan Static Analysis to a PHP Library](https://getrush.ai/run/add-phpstan/php/)
- [Fix `Call to undefined function create_function()` after moving to PHP 8](https://getrush.ai/run/fix-create-function-removed/php/)

## The same job on other stacks

- [Upgrade PHPUnit in a Slim 4 App](https://getrush.ai/run/upgrade-phpunit/slim/)

## More jobs like this: Upgrade dependencies weekly

- [Upgrade Pinia 2 to Pinia 4 in a Vue 3 App](https://getrush.ai/run/upgrade-pinia/pinia/)
- [Upgrade Playwright and Its Browsers in a Test Suite](https://getrush.ai/run/upgrade-playwright/playwright/)

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