non-technical notes

Base Setup

Follow the instructions at:

https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/core/+/refs/heads/master/DEVELOPERS.md

nota bene: supplemental dev env set up

Though this is covered in the documentation, to sum up the important parts

1. add xdebug configuration to .env

make sure .env includes

XDEBUG_CONFIG='mode=debug start_with_request=trigger client_host=host.docker.internal client_port=9003 idekey=vscode'
XDEBUG_MODE=debug

2. make sure host.docker.internal is routed to the host

make sure docker-compose.override.yml contains this:

services:
  mediawiki:
    # For Linux: This extra_hosts section enables Xdebug-IDE communication:
    extra_hosts:
      - "host.docker.internal:host-gateway"

vscode setup

3. install PHP Debug extension

install the PHP Debug extension to VSCode

4. add debug launch configuration

Open the launch.json configuration. Find this in the menu under “Run > Open Configurations”. Add the following:

        {
            "name": "mediawiki debug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html/w": "${workspaceFolder}",
            }
        }

Conclusion

You should now be able to run the “mediawiki debug” launch configuration, add a breakpoint, and step through an execution.