Jump to content

PHP upgrade process for MediaWiki

From Wikitech

PHP Upgrade Process for MediaWiki at WMF.

Preparation for MediaWiki

This applies to every new PHP version that MediaWiki supports, including intermediary versions of PHP that WMF does not install. For example, while WMF stayed on PHP 7.4, MediaWiki added support for PHP 8.0, 8.1, 8.2, and 8.3. WMF then upgraded to PHP 8.1.

This is partly for efficiency, because it means WMF will only have to maintain Debian packages for PHP versions that it deploys, and thus these steps start with sury.org with only the production versions eventually switching to wikimedia.org.

  1. CI: Create RelEng docker images for Jenkins "Quibble" jobs with PHP X.Y, in integration/config.git, using Debian packages from sury.org.
  2. CI: Enable experimental Jenkins jobs with PHP X.Y in Zuul, for all MediaWiki repositories. These only run when someone comments "check experimental" on a patch, since they are most likely failing at this point.
  3. DX: Create RelEng docker images for MediaWiki-Docker with PHP X.Y, to allow local people to opt-in and discover issues via local development.
  4. MW: Make CI for MediaWiki core and WMF extensions pass on PHP X.Y.
    • Initial review of upstream PHP X.Y announcements, deprecations, changelog, and RFCs. Identify relevant changes and where MediaWiki core/extensions are affected in the most prominently or most difficult way so that we can plan code migrations, especially if it affects a stable or public MediaWiki API, or a third-party Composer package that MediaWiki depends on where an upstream must make changes for us first. Report such issues to relevant upstreams, and try to send a pull request along with it.
    • Initial review of MediaWiki Composer dependencies (identify any semver-major upstream releases that we cannot apply today due to a too-high PHP version requirement, that our upcoming PHP X.Y upgrade would unblock). Create subtasks for each of these, so that people can work on preparing code using these dependencies to be forward-compatible with the next major version (during prep and rollout phases, we will apply these composer upgrades during the post-rollout-pre-release phrase, before the MW release branch cut).
    • Fix deprecation warnings in MediaWiki core and WMF-deployed extensions (enough for CI to pass).
    • Enforce Jenkins jobs for PHP X.Y on MediaWiki core and WMF-deployed extensions ("voting" mode).
    • Create subtasks for any non-trivial failures detected by PHPUnit.
  5. DX: Switch MediaWiki-Docker default to PHP X.Y, matching the next PHP version that WMF will deploy.

Preparation for WMF

Adoption of Debian packages from wikimedia.org in CI and DX serves several purposes:
  • It avoid regressing or delaying migration of CI and local workflows that rely on packages that otherwise might not be available.[1]
  • It increases the value (ROI) of everyone's CI and local development activities at no extra cost.
  • It increases confidence in the results by avoiding situations where the "PHP X.Y" local/CI env is taken to be the same as prod, but then revealed to have a difference not found until production due to differences in package versions or otherwise missing backports for bugs already known and fixed.
  1. SRE: Create Debian packages for PHP X.Y and upload to apt.wikimedia.org.
  2. CI: Update RelEng docker images for Jenkins "Quibble" jobs with PHP X.Y, to install packages from wikimedia.org instead of sury.org.
  3. DX: Update RelEng docker images for MediaWiki-Docker with PHP X.Y, to install packages from wikimedia.org instead of sury.org.
  4. SRE: Deploy title-case mapping in MediaWiki configuration (wmf-config/UcfirstOverrides.php), to ensure page titles and user names remain unchanged during the upcoming upgrade, by overriding the "next" PHP version to behave the same as the "old" PHP version.
  5. SRE: Switch mw-debug/next to PHP X.Y images, for public opt-in testing via WikimediaDebug.

Test

  1. MW: Monitor and fix deprecation warnings as found in Logstash. Create a tracking task (e.g. T379874) and routinely monitor Logstash for production errors that are PHP deprecations, create tasks for them, tag with PHP X.Y (e.g. #php_8.3_support), and attach them as child tasks under this tracking task. Review existing tasks on the PHP X.Y Phabricator board and make progress on those (either directly or by escalating to someone in/outside the team).
  2. QTE, MW, SRE: Validation and end-to-end testing, especially areas not covered by CI.
  3. SRE, MW: Benchmarking for PHP X.Y, check specific well-known workloads to identify regressions or suboptimal configurations (e.g. benchmw with URLs, and CLI benchmarkParse.php). Previous examplesː T383805, T280497.

Rollout

  1. Beta Cluster: Switch to PHP X.Y.
  2. SRE: Ramp up mw-api-ext and mw-web cluster (cookie-based).
  3. SRE: Ramp up mw-api-int, mw-jobrunner.
  4. SRE: Ramp up mw-api-ext and mw-web cluster (remaining).
  5. SRE: Switch other mw-on-k8s server groups (mw-script, mw-cron, mw-experimental, mediawiki-dumps-legacy, etc) and the deployment server.

Post-rollout

To take place before the next MW release branch cut, but after the rollout. The branch is generally cut two months before the release month (e.g. in April if the release is in June). mw:Version lifecycle

  1. MW: Raise minimum PHP version if applicable, as expected under policy (table).
  2. MW: Upgrade vendor dependencies if applicable.

To take place after the rollout, and after the MW release branch cut (e.g. late April or early May, if the release is in June)

  1. SRE: Turn down cookie-based routing and other "next" handling, validating that no workloads still run on the old PHP version (which would hard-fail at this point).
  2. SRE: Remove emulating of old-php title-case mapping. T394556

Post-rollout (MediaWiki release)

See mw:Release checklist.

Out of scope

The following may be associated or historically paired with PHP upgrades that are now handled separately:

  • OS upgrade (Debian Linux).
  • libicu upgrades (Re-indexing and re-encoding the MediaWiki category collations).
  1. ↑ For example: In July 2025, Wikimedia created a Debian package for php-xhprof and started hosting it on apt.wikimedia.org. At the time of writing, upstream Debian does not provide xhprof in any of the "stable" or "testing" channels.
Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=PHP_upgrade_process_for_MediaWiki&oldid=2363625"