All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

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

The same job on other stacks

More jobs like this: Upgrade dependencies weekly

Keep reading