What the agent does
The agent reads how the app pins the framework before touching Composer. In an app created from the cakephp/app skeleton, composer.json requires cakephp/cakephp as 5.4.*, a wildcard on the patch number only, so composer update never crosses to the next minor until someone edits that line. Around it sit cakephp/migrations ^5.0 and cakephp/plugin-installer ^2.0, and in require-dev cakephp/bake ^3.6, cakephp/debug_kit ^5.2, cakephp/cakephp-codesniffer ^5.3 and a PHPUnit constraint that spans three majors. .github/dependabot.yml already asks for weekly Composer and GitHub Actions updates, with at most ten open pull requests each.
It asks Packagist for the newest 5.x minor, edits the constraint to it, and runs composer why-not cakephp/cakephp for that version to see which plugin, if any, refuses it. A blocker gets its own constraint raised in the same change; one with no compatible release yet is reported, and the upgrade stops there with nothing half-applied. Then it runs composer update cakephp/cakephp --with-all-dependencies. The skeleton tracks no composer.lock; in an app that does, the lock is updated in the same commit.
Then it finds what the new version complains about. config/app.php sets Error.errorLevel to E_ALL with an empty ignoredDeprecationPaths, so deprecation notices are not hidden, and the agent runs vendor/bin/phpunit and reads every one. It opens the migration guide for that minor in the CakePHP book with the sandbox's browser, checks whether the cakephp/upgrade tool ships a rector set for it, and applies the set to src/, tests/, config/ and templates/ when it does. What rector cannot rewrite it changes by hand, one deprecation at a time, rerunning the tests after each.
A minor release also changes the skeleton itself: new keys in config/app.php, a line in config/bootstrap.php, a middleware in src/Application.php. The agent diffs the app's config/ and src/Application.php against the skeleton's tag for the target minor and lists each difference in the pull request as adopted or left for you, without overwriting local changes. It finishes with composer check, which is PHPUnit and then phpcs, and PHPStan at the level 8 in phpstan.neon, once with the highest dependency versions and once with composer update --prefer-lowest, the two ends the CI matrix installs.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Upgrade this CakePHP 5 app to the newest 5.x minor release on Packagist. Read composer.json, composer.lock if it is tracked, .github/workflows/ci.yml, .github/dependabot.yml, phpunit.xml.dist, phpstan.neon, phpcs.xml, config/app.php, config/bootstrap.php, config/plugins.php and src/Application.php first. Change the cakephp/cakephp constraint to the target minor, run composer why-not for it, and raise the constraint of any plugin that blocks it; if a plugin has no compatible release, stop and report that instead of forcing it. Run composer update with all dependencies. Run vendor/bin/phpunit and collect every deprecation notice, read the migration guide for the target minor, use the cakephp/upgrade rector set for it if one exists, and fix the remaining deprecations by hand. Diff config/ and src/Application.php against the cakephp/app skeleton at the tag for the target minor and list each difference as adopted or left alone; do not overwrite local changes. Run composer check and PHPStan with the highest dependency versions and again after composer update --prefer-lowest. Open one pull request with the version before and after, each deprecation and its fix, the skeleton differences, and the output of every command.",
"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
One pull request comes back. It changes composer.json (and composer.lock where the app tracks one), the files where a deprecated call was replaced, and any skeleton change the agent adopted. Its description states the framework version before and after, the plugins whose constraints moved and why, a table of each deprecation with the file and the replacement, and the PHPUnit, phpcs and PHPStan output for both the highest and the lowest dependency sets.
In a repository that keeps the skeleton's workflow, the testsuite job then runs the branch on PHP 8.2 with the lowest versions and PHP 8.5 with the highest, and the coding-standard job runs phpcs and PHPStan 2.3. Those are the same two ends the agent ran in its sandbox, so a red check there means the environments differ, and the description says which PHP version the sandbox used.
A reviewer reads the skeleton list first, because it holds the choices: a new configuration key the agent left out, a default that changed. The deprecation table is mechanical by comparison. When a plugin blocked the upgrade, there is no code change at all; the pull request is replaced by a report naming the plugin, the version it supports and the issue or release to watch.
Run it on every Monday morning
In the console, add an automation to the Project with this prompt and a schedule trigger whose cron is an early Monday hour in your timezone. Most weeks the run finds the app already on the newest minor and reports that in a sentence with no pull request; the week a release appears, the upgrade is waiting for review before anyone has read the announcement. Word the prompt so a run that finds an open upgrade pull request from a previous week updates that branch and does not open another.
For many apps, send the same body from your own scheduler to POST /o/{org}/sessions, one call per repository, each with a request_id that is a UUID v5 of the repository's full name and the ISO week, so a retry within the week returns the run already started.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
A framework upgrade is mostly running things and reading what they print: Composer's reasons for refusing a version, a long list of deprecation notices, static analysis at level 8, the suite at two dependency sets. The agent does all of it in a sandbox of its own, so nothing is installed or left half-updated on a developer's machine, and every command and its output is kept with the run. The pull request quotes that output, which is the difference between a version bump someone hopes is safe and one that has been exercised.
Dependabot, already configured in the skeleton, proposes version changes; it does not rewrite a deprecated call or compare your config/app.php with the skeleton's. The run covers that second half, and because each run is isolated, a team with many CakePHP apps can upgrade them the same morning and review descriptions written to one shape.
Frequently asked questions
Can it do a major upgrade, such as CakePHP 4 to 5?
Yes, but ask for it by name: a major upgrade removes what earlier minors deprecated, so the agent first brings the app to the last minor of its current major with zero deprecation notices, then crosses over. Expect that to be several pull requests, each with its own test output, not one.
What happens when a plugin does not support the new version yet?
The agent stops before changing anything. composer why-not names the package and the constraint that refuses the target, and the run ends with that report and no pull request. Next week's run checks again.
Does it overwrite my config/app.php with the skeleton's?
No. It diffs the two and lists each difference. A new key with a safe default may be added and is named in the description; anything that would change behaviour, or that you have edited locally, is left alone and listed for you to decide.
Why run the tests with the lowest dependency versions too?
Because the skeleton's CI does: its matrix has a PHP 8.2 row with dependencies: lowest. An upgrade that passes only with the newest versions of everything would turn that row red, so the agent runs composer update --prefer-lowest and the suite again before opening the pull request.
Is this different from the Dependabot pull requests I already get?
It complements them. Dependabot raises versions on a schedule and leaves the code as it is. This run raises the framework, reads the notices the new version prints, fixes the calls they name and shows the suite passing afterwards.