Jump to content

This is a read-only backup copy of Wikitech. The live site can be found at wikitech.wikimedia.org

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 docker images in integration/config.git with PHP X.Y using Debian packages from sury.org . These are for the Jenkins "Quibble" jobs.
  2. CI: Create Jenkins jobs with PHP X.Y, and enable as "experimental" in Zuul for all MediaWiki repositories. Experimental jobs only run when someone comments "check experimental" in Gerrit and do not block code review, because they likely do not pass yet at this point.
  3. DX: Create docker images in releng/dev-images.git with PHP X.Y. These let MediaWiki-Docker users opt-in and reproduce/discover/fix issues locally.
  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. Create tasks for relevant changes that might affect MediaWiki core/extensions in a prominent or difficult-to-migrate way, so that we can plan ahead. 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 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 to be forward-compatible with the next major version of these dependencies (we will apply these composer upgrades during the post-rollout phase, before the MW release branch cut).
    • Fix deprecation warnings in MediaWiki core and WMF-deployed extensions (enough for CI to pass).
    • Create subtasks for any non-trivial failures detected by PHPUnit.
    • Promote Jenkins jobs with PHP X.Y on MediaWiki core and WMF-deployed extensions from "experimental" to "gate-and-submit" pipeline. This CI enforces that they must pass and block code review.
  5. DX: Switch MediaWiki-Docker default to PHP X.Y, thus matching the next PHP version that WMF will deploy. This is configured in mediawiki/core.git:/docker-compose.yml .

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 . This will involve coordination with MW to review the selected PHP extension package versions. In rare cases, additional MW effort may be required to migrate to a suitable alternative if an in-use extension is no longer supported on PHP X.Y. Previous example: T398245 .
  2. CI: Switch PHP X.Y images in integration/config.git from sury.org to wikimedia.org and apply to Jenkins jobs.
  3. DX: Switch PHP X.Y images in releng/dev-images.git from sury.org to wikimedia.org and apply update to MediaWiki-Docker. This is configured in mediawiki/core.git:/docker-compose.yml .
  4. SRE: Create production images for PHP X.Y and add new flavour to MediaWiki deployments. This means Scap deployments will build both container flavours going forward. The new PHP X.Y flavour is for internal use, only to facilitate creation of the title-case mapping. Once that is done, the image can be exposed publicly via mw-debug/next. Previous examples: T398246 for production images, T399884 for the dependent MediaWiki image flavour.
  5. SRE: Generate and deploy title-case mapping in MediaWiki configuration (wmf-config/UcfirstOverrides.php). This ensures 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. Note that this may not be needed if both versions of PHP support the same Unicode version. Previous example: T401252 .
  6. SRE: Switch mw-debug/next to PHP X.Y images, for public opt-in testing via WikimediaDebug. By this point, the infrastructure for mw-on-k8s is ready to begin the rollout. Previous example: T401254 .
  7. Beta Cluster: Switch to PHP X.Y, includes writing Puppet changes to support PHP X.Y on baremetal. By this point, the infrastructure for baremetal servers (parsoidtest and deployment server) is ready for rollout.
  8. SRE: Change Scap to use PHP X.Y images when invoking maintenance scripts, and upgrade Scap in Beta Cluster and production. This is controlled by mediawiki_runtime_image and applies to rebuildLocalisationCache.php. Previous example: scap change 1044 , T411235 .
  9. DX: Switch Catalyst/Patchdemo to PHP X.Y. This aligns Patchdemo with Beta Cluster, MediaWiki-Docker, and CI for consistency; and prevents unexpected breakage post-rollout when we raise the minimum PHP version in MediaWiki. Previous example: T411277 .

Test

  1. MW: Start monitoring and fixing deprecation warnings as found in Logstash. Create a tracking task (e.g. T401855 ) and regularly 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: One week for validation and end-to-end testing via WikimediaDebug "next" and Beta Cluster. This is the last oppertunity to discover and resolve blockers early, before rolling out to a small percentage of real traffic.
  3. SRE, MW: Benchmarking for PHP X.Y, check specific well-known workloads to idetnify regressions or suboptimal configurations (e.g. benchmw with URLs, and CLI benchmarkParse.php). Previous examplesː T383805 , T280497 .
  4. SRE, MW: Update the production parsoid testing environment to PHP X.Y and work with Content Transform to validate its operation (e.g., round-trip testing ). This should happen after testing in WikimediaDebug has made substantial progress. Previous example: T403772 (note: this workload may migrate to k8s before the next upgrade - see T386246 ).

Rollout

The rollout begins with final preparation steps to introduce PHP X.Y workloads in production and enable their use (e.g., the ability to route traffic to them). Once those steps are complete, the migration begins, and proceeds over 4 logical groups of workloads:

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

These groups begin migration in the order above, but in practice there is some amount of pipelining (e.g., #2 can begin shortly after #1 does, while #3 must wait for #1 to complete). Previous example: T405955 . See also MediaWiki PHP 8.3 upgrade schedule (theoretical) (restricted, Google Sheet).

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). Previous example: T405955 (see Cleanup items).
  2. SRE: Remove emulation of old-PHP title-case mapping. This can be skipped if no title-case mapping was necessary. Previous example: 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=2371309 "