Jump to content

User:Ollie Shotton (WMDE)/Drafts/Integration with JetBrains IDEs

From mediawiki.org

The run/debug configurations feature of JetBrains IDEs is useful, but a challenge to get working with mwcli. This guide aims to take you through the steps necessary to integrate the PHP interpreter that's part of mwcli with JetBrains IDEs. PhpStorm (version 2023.3.1) is used in the screenshots, but the process should be similar for other JetBrains IDEs (e.g. IDEA).

Prerequisites

[edit]
  1. mwcli has been installed
  2. a MediaWiki instance has been created with mwcli (see First Setup)
  3. the following JetBrains plugins are installed and enabled (File → Settings → Plugins):
    • Docker
    • PHP Docker
    • PHP Remote Interpreter

Configure Docker

[edit]
  1. Open the Settings window in the IDE (File → Settings)
  2. Go to the Docker settings by expanding the Build, Execution, Deployment section in the side menu and clicking on Docker
  3. Add a new Docker connection by clicking the ➕ icon
  4. The correct setting should already be filled out. If not, enter the correct settings to connect to the Docker daemon. You can test the connection by clicking the Refresh button to the right of Connect to Docker daemon with:.
  5. Click the Apply button in the Settings window

Configure the PHP CLI Interpreter

[edit]
  1. Open the Settings window in the IDE (File → Settings)
  2. Go to the PHP interpreter setting by clicking on PHP in the side menu
  3. Set the PHP language level: to the minimum supported PHP version of your project
  4. Open the CLI Interpreters window by clicking the button with the three dots next to the CLI Interpreter: dropdown
  5. Add a new From Docker, Vagrant, VM, WSL, Remote… interpreter by clicking the ➕ icon
  6. In the Configure Remote PHP Interpreter window:
    1. Select the Docker Compose radio button
    2. Ensure the Server: dropdown is set to the Docker connection created in the #Configure Docker section
    3. Open the Docker Compose Configuration Files window by clicking the Browse... folder icon in the Configuration files: input box
      1. If the IDE has automatically found and added the docker-compose.yml file, remove it using the remove (➖) button
      2. Click the add (➕) button in the Docker Compose Configuration Files window. Use the Choose Configuration File or Folder window to select the relevant mwcli docker compose yml files:
        1. Click the Show Hidden Files and Directories icon (hover over the icons to see what each of them are)
        2. Navigate to the /home/USER/.config/mwcli/mwdd/default directory (substituting USER with your username)
        3. While holding the Ctrl key, select the base.yml, mediawiki.yml, and mysql.yml files
        4. Click the OK button in the Choose Configuration File or Folder window
      3. Click the OK button in the Docker Compose Configuration Files window
    4. Select mediawiki from the Service: dropdown
    5. Add the environment variables:
      1. Add the following to the Environment variables: input box (substituting USER with your username) 
        COMPOSE_PROJECT_NAME=mwcli-mwdd-default;MEDIAWIKI_VOLUMES_CODE=/home/USER/git/gerrit/mediawiki/core;MEDIAWIKI_VOLUMES_DOT_COMPOSER=/home/USER/.composer;MEDIAWIKI_XDEBUG_CONFIG=client_host=172.17.0.1;PORT=8080
      2. Tip: you might find it easier to click the Edit environment variables icon to substitute your username in the Environment Variables window
      3. Click the OK button in the Environment Variables window
    6. Make sure the PHP interpreter path: is php
    7. Click the OK button in the Configure Remote PHP Interpreter window
  7. Back in the CLI Interpreters window, change the Name: of the newly create interpreter to mwcli [docker compose]
  8. (Optional) deselect the Visible only for this project if you want to be able to use this mwcli PHP interpreter across multiple JetBrains projects
    mwcli doesn't work well as a generic PHP interpreter as it has MediaWiki specific configuration
  9. Under Lifecycle, select the Connect to existing container ('docker-compose exec') radio button
  10. Under General, check the PHP version: has been identified correctly - if it hasn't, go back and check the instructions, something has gone wrong
  11. Click the OK button in the CLI Interpreters window
  12. The CLI Interpreter: should have automatically selected the newly created mwcli [docker compose] interpreter
  13. Set up the path mappings between the files in the container and the files in the local project
    1. Click on the folder icon in the Path mappings: text field to open the Edit Project Path Mappings window
    2. Click the plus icon in the top left of the Edit Project Path Mappings window to add a new path mapping
    3. Set the Local Path and Remote Path as per this table:
      Local PathRemote Path
      /home/USER/git/gerrit/mediawiki/core
      (the root of your local MediaWiki core repo)      		/var/www/html/w
      Make sure there is no whitespace before or after the paths in the mapping
    4. Click the OK button in the Edit Project Path Mappings window
  14. Click the Apply button in the Settings window
  15. You can now run PHP tests directly from the IDE by clicking the green run buttons

Configure PHP_CodeSniffer

[edit]
  2. Open the Settings window in the IDE (File → Settings)
  3. Open the PHP_CodeSniffer settings by expanding PHP and Quality Tools in the side menu
  4. Change Configuration: dropdown to By default project interpreter
  5. Click the OK button

Configure the Xdebug debugger

[edit]
  1. Make sure you have followed the #Configure the PHP CLI Interpreter steps
  2. Configure a PHP server in the IDE
    1. Open the Settings window (File → Settings)
    2. Expand the PHP section in the side menu and click on Servers
    3. Add a new configuration by clicking the plus icon
    4. Set the Name: to mwcli
    5. Set the Host to default.mediawiki.mwdd.localhost
    6. Set the Port to 8080
    7. Click the Use path mappings checkbox
    8. Map the File/Directory of your MediaWiki repo to the Absolute path on the server as /var/www/html/w
    9. Click the OK button in the Settings window
  3. Add mwcli environment variable
    1. In a terminal execute mw dev env set MEDIAWIKI_XDEBUG_CONFIG "client_host=172.17.0.1"
    2. The output of mw dev env list should include MEDIAWIKI_XDEBUG_CONFIG=client_host=172.17.0.1
  4. Debug code from the IDE
    1. Add breakpoint(s) where you want to stop execution and inspect variables
    2. Run the code in Debug mode (e.g. run PHPUnit test(s) that execute the code with the breakpoint(s))
    3. See the program stop at the breakpoint(s)
Retrieved from "https://www.mediawiki.org/w/index.php?title=User:Ollie_Shotton_(WMDE)/Drafts/Integration_with_JetBrains_IDEs&oldid=6329527"