Configure Xdebug and update contributing docs

.vscode/launch.json

@@ -5,7 +5,7 @@
       "name": "Listen for Stream XDebug",
       "type": "php",
       "request": "launch",
-      "port": 9000,
+      "port": 9003,
       "ignore": [
         "vendor/"
       ],
@@ -16,4 +16,4 @@
       }
     }
   ]
-}
+}

contributing.md

@@ -28,7 +28,14 @@ We suggest using the [Homebrew package manager](https://brew.sh) on macOS to ins
 
 ### PHP Xdebug
 
-The WordPress container includes the [Xdebug PHP extension](https://xdebug.org). It is configured to [autostart](https://xdebug.org/docs/remote#remote_autostart) and to [automatically detect the IP address of the connecting client](https://xdebug.org/docs/remote#remote_connect_back) running in your code editor. See [`.vscode/launch.json`](.vscode/launch.json) for the directory mapping from the WordPress container to the project directory in your code editor.
+The WordPress container includes the [Xdebug PHP extension](https://xdebug.org). It is configured in the [`php.ini`](./local/docker/wordpress/php.ini) file to work in the [develop, debug and coverage modes](https://xdebug.org/docs/step_debug#mode).
+
+[Step Debugging](https://xdebug.org/docs/step_debug) should work out of the box in VSCode thanks to the configuration file, [`.vscode/launch.json`](.vscode/launch.json). It contains the directory mapping from the WordPress container to the project directory in your code editor.
+
+In order to set up Step Debugging in PhpStorm, follow the [official guide](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html). Make sure to set up the same directory mappings as defined for VSCode in [`.vscode/launch.json`](.vscode/launch.json), e.g.:
+- `${workspaceRoot}` -> `/var/www/html/wp-content/plugins/stream-src`,
+- `${workspaceRoot}/build` -> `/var/www/html/wp-content/plugins/stream`,
+- `${workspaceRoot}/local/public` -> `/var/www/html`
 
 ### Mail Catcher
 
@@ -38,14 +45,13 @@ We use a [MailHog](https://github.com/mailhog/MailHog) container to capture all
 
 We use npm as the canonical task runner for the project. The following commands are available:
 
+- `npm run start` to start the project's Docker containers.
+- `npm run stop` to stop the project's Docker containers.
+- `npm run stop-all` to stop _all_ Docker containers.
 - `npm run build` to build the plugin JS and CSS files.
-
 - `npm run lint` to check JS and PHP files for syntax and style issues.
-
 - `npm run deploy` to deploy the plugin to the WordPress.org repository.
-
 - `npm run cli -- wp info` where `wp info` is the CLI command to run inside the WordPress container. For example, use `npm run cli -- ls -lah` to list all files in the root of the WordPress installation.
-
 - `npm run test` to run PHPunit tests inside the WordPress container.
 
 

docker-compose.yml

@@ -21,16 +21,15 @@ services:
     ports:
       - "80:80"
       - "443:443"
-      - "9000:9000" # Xdebug
     volumes:
       - .:/var/www/html/wp-content/plugins/stream-src # Working directory.
       - ./build:/var/www/html/wp-content/plugins/stream # Built version for testing.
       - ./local/public:/var/www/html # WP core files.
     restart: always
+    extra_hosts:
+      - host.docker.internal:host-gateway
     environment:
       APACHE_RUN_USER: "#1000" # Ensure Apache can write to the filesystem.
-      XDEBUG_MODE: coverage
-      XDEBUG_CONFIG: ${XDEBUG_CONFIG:-remote_host=host.docker.internal remote_connect_back=0}
       WP_TESTS_DIR: /var/www/html/wp-content/plugins/stream-src/vendor/wp-phpunit/wp-phpunit
       WP_PHPUNIT__TESTS_CONFIG: /var/www/html/wp-tests-config.php
       SMTPSERVER: mailhog

local/docker/wordpress/Dockerfile

@@ -3,8 +3,9 @@ ARG PHP_VERSION=7.4
 
 FROM wordpress:php${PHP_VERSION}-apache
 
-# Default version which supports the default PHP 7.4.
-ARG XDEBUG_VERSION=2.9.6
+# The latest Xdebug version which supports PHP 7.4 is 3.1.6.
+# @link https://xdebug.org/docs/compat
+ARG XDEBUG_VERSION=3.1.6
 
 # Include our Composer vendor binary path into global path.
 ENV PATH="/var/www/html/wp-content/plugins/stream-src/vendor/bin:${PATH}"
@@ -19,6 +20,6 @@ RUN apt-get update; \
 
 COPY php.ini /usr/local/etc/php/php.ini
 
-# Setup xdebug. The latest version supported by PHP 5.6 is 2.5.5.
-RUN	pecl install "xdebug-${XDEBUG_VERSION}"; \
-	docker-php-ext-enable xdebug
+# Setup xdebug.
+RUN pecl install "xdebug-${XDEBUG_VERSION}"
+RUN docker-php-ext-enable xdebug

local/docker/wordpress/php.ini

@@ -8,13 +8,11 @@ sendmail_path = "/usr/bin/msmtp --port=1025 --read-recipients"
 
 ; Enable remote Xdebug.
 [xdebug]
+xdebug.mode = coverage,debug,develop
+xdebug.start_with_request = yes
+xdebug.client_host = host.docker.internal
+xdebug.discover_client_host = 0
 xdebug.remote_enable = 1
-; Xdebug server running on this container will try to connect back to
-; port 9000 of the IP making the request (discovered through the
-; REMOTE_ADDR or HTTP_X_FORWARDED_FOR). This doesn't work on
-; macOS where the Docker containers can't reach the macOS
-; host through the internal network.
-xdebug.remote_connect_back = 1
 xdebug.scream = 1
 xdebug.profiler_enable_trigger = 1
 xdebug.trace_enable_trigger = 1