MirLabs / The blog

Keeping Symfony apps patched without spending evenings on composer update

· Cyril Delage

A patch release is out, maybe a security one. You open the project, run composer update, read the diff of composer.lock, run the tests, push, deploy. Then the next project. Multiply by every app you look after and patching becomes the job nobody schedules, until a CVE schedules it for you.

I maintain several Symfony sites, and I wanted the routine part of that evening done by a machine, with the decisions still mine. That is Uplift, an MIT-licensed bundle.

What a run does

Uplift has three commands. uplift:plan reads composer.json, composer.lock, composer outdated --direct, Packagist and php.net, and gives every possible move (PHP, Symfony, each direct dependency) a size, patch, minor or major, and a decision: apply (the policy allows it), propose (it works, but a person decides) or blocked (with the reason).

uplift:apply does the apply moves:

  1. it rewrites composer.json only where a move goes past a constraint, keeping the way it was written (7.4.* -> 8.0.*, ^0.3 -> ^0.4, ^6.4 || ^7.0 -> ^6.4 || ^7.0 || ^8.0), plus extra.symfony.require and, for PHP, config.platform.php. No reordering, no re-indenting;
  2. it runs composer update for the moved packages only, each pinned to its target with --with vendor/package:1.2.3 --with-dependencies. If composer cannot resolve them, both files are put back;
  3. it runs Rector when the project has a rector.php;
  4. it runs your tests;
  5. it writes var/uplift/report.json and var/uplift/report.md.

The third command, uplift:adopt, looks for code written by hand before a feature existed (a protected static $defaultName that could be #[AsCommand], for instance). It parses the code statically and never runs it.

The policy lives in the environment

What may move is not in YAML, it is in environment variables, so each server or CI job decides without a code change:

UPLIFT_ENABLED=1
UPLIFT_PHP=off
UPLIFT_SYMFONY=patch
UPLIFT_PACKAGES=patch
UPLIFT_PHP_MAX=8.3
UPLIFT_TEST_COMMAND=vendor/bin/phpunit

That is the policy my own sites run with. Each level (off, patch, minor, major) is the largest move done automatically; anything larger is proposed in the report and waits. The defaults are cautious: UPLIFT_ENABLED=0 (at 0, uplift:apply changes nothing, uplift:plan still plans) and patches only. A wrong value such as UPLIFT_PHP=all is an error, never a silent default.

UPLIFT_PHP_MAX is the one I would point out to anyone working in a company. Some servers cannot go above a PHP version because the operating system ships it. With a ceiling, PHP never moves above it, and a release of any package that needs a newer PHP is blocked, with the reason in the report: requires PHP >=8.2, above UPLIFT_PHP_MAX=8.1.

One step at a time

With UPLIFT_SYMFONY=major, Uplift still does not jump from 6.2 to the latest 8.x. It moves the way upgrade guides do: first to the last minor of the current major, where every deprecation of the next one shows (6.2 -> 6.4), then to the next major only, on a later run. PHP moves one branch per run (8.1 -> 8.2, never 8.1 -> 8.4). The plan shows the whole way ahead:

symfony/*: 7.3.5 -> 7.4.8 now; then 8.1.2 in later runs

Tests are the gate

The upgrade is only as safe as the command in UPLIFT_TEST_COMMAND. If it fails, uplift:apply exits with code 1 and the report says why. Adoptions go through the same gate one by one: Rector runs on the candidate files of one feature, the tests run, and if they fail those files are put back before the next feature is tried. The experimental readonly-promotion adoption is off by default for that reason: code writing through reflection (Serializer, Form, Doctrine hydrating a non-entity) fails at run time, where a static scan cannot see it.

If your test suite is thin, Uplift will happily report an upgrade as passed. It cannot know more than your tests.

It never pushes, never deploys

This is the choice I care most about. Uplift leaves a branch and a report; whatever runs it decides what happens next:

php bin/console uplift:apply --branch=upgrade/2026-11 --commit

The README has a complete GitHub Actions workflow that runs this once a month and pushes the branch only when something moved. Who validates is one more variable, UPLIFT_HUMAN_VALIDATION: at 1 (the default) the branch waits for a person, as a pull request or a change in Rehearsal, an admin page where you validate or reject each change. At 0, the job may merge an upgrade whose tests passed and deploy it.

Rolling back, and not trying again

Shipping without a person only makes sense with a way back. That way back is UPLIFT_SKIP: a list of package@version releases never to move to (symfony@7.4.18 for the framework). A deploy that breaks the site goes back to the previous release, reverts the upgrade commit and adds each moved release to UPLIFT_SKIP. The next run takes the release below it if the level allows, and tries again when a newer one comes out. A bad release costs one failed deploy, once.

The deploy and rollback part is not in the bundle; it belongs to your pipeline. On my own server it is a nightly shell script. For each site with Uplift installed, it makes a git worktree on an upgrade/<date> branch, never touching the live checkout. It runs uplift:apply in a throwaway container started from the site's running PHP image, with the dev dependencies and, when the tests need one, a throwaway database. It merges fast-forward when the tests passed and validation is off, and writes the skip list after a rollback.

What it does not do

  • It moves direct dependencies; transitive ones follow only as far as the direct ones need.
  • It does not change your runtime: a PHP move changes composer.json, and your Docker image or server must follow.
  • Constraints it cannot carry over (>=1.0 <2.0, branches) are left to you, and pre-releases are never candidates.
  • It needs PHP 8.1 and Symfony 6.4 or later. Catching up from Symfony 4 or 5 is a project for a person, and the README describes the manual path.

Try it

composer require acencyril/uplift-bundle
php bin/console uplift:plan
php bin/console uplift:adopt

uplift:plan and uplift:adopt change nothing, so you can run them on any project today and read how far behind it is. When you are ready, set UPLIFT_ENABLED=1 in a CI job or on a server and run uplift:apply --branch=… --commit.

The current version is 0.5.0; the changelog lists every behaviour change. Issues and feedback are welcome on GitHub, especially from teams keeping many Symfony apps up to date.

Patching should be a decision you make in the morning, not an evening you lose.

A project like this one?AI integration, a site to make readable by assistants, security: let's talk.
Contact me

Read next