Add debugging section to the core manual

resolves #551

Author: hschaeidt

core/debugging.md

@@ -0,0 +1,93 @@
+# Debugging
+
+The default Docker stack is shipped without a Xdebug stage. It's easy
+though to add [Xdebug](https://xdebug.org/) to your project, for development
+purposes such as debugging tests or api requests remotely.
+
+## Add a development stage to the Dockerfile
+
+To avoid deploying API Platform to production with an active Xdebug extension,
+it's recommended to add a custom stage to the `api/Dockerfile`. See the
+following diff for a working example.
+
+```diff
+diff --git a/api/Dockerfile b/api/Dockerfile
+index 745a8f9..432f0d9 100644
+--- a/api/Dockerfile
++++ b/api/Dockerfile
+@@ -1,11 +1,12 @@
+# the different stages of this Dockerfile are meant to be built into separate images
+# https://docs.docker.com/compose/compose-file/#target
+
++ARG BUILD_ENV=prod
+ARG PHP_VERSION=7.2
+ARG NGINX_VERSION=1.15
+ARG VARNISH_VERSION=6.0
+
+-FROM php:${PHP_VERSION}-fpm-alpine AS api_platform_php
++FROM php:${PHP_VERSION}-fpm-alpine AS api_platform_php_prod
+
+# persistent / runtime deps
+RUN apk add --no-cache \
+@@ -51,6 +52,15 @@ RUN set -eux; \
+       \
+       apk del .build-deps
+
++FROM api_platform_php_prod as api_platform_php_dev
++
++ARG XDEBUG_VERSION=2.6.0
++RUN apk add --no-cache $PHPIZE_DEPS; \
++    pecl install xdebug-$XDEBUG_VERSION; \
++    docker-php-ext-enable xdebug
++
++FROM api_platform_php_${BUILD_ENV} as api_platform_php
++
+COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
+COPY docker/php/php.ini /usr/local/etc/php/php.ini
+```
+
+Now when building the stack with the `BUILD_ENV=dev` flag, Xdebug is
+successfully available.
+
+Inspect the installation with the following command, the requested Xdebug
+version should be displayed in the output.
+
+```bash
+$ docker-compose exec php php --version
+
+PHP 7.2.8 (cli) (built: Jul 21 2018 08:09:37) ( NTS )
+Copyright (c) 1997-2018 The PHP Group
+Zend Engine v3.2.0, Copyright (c) 1998-2018 Zend Technologies
+    with Zend OPcache v7.2.8, Copyright (c) 1999-2018, by Zend Technologies
+    with Xdebug v2.6.0, Copyright (c) 2002-2018, by Derick Rethans
+```
+
+## Configure Xdebug with docker-compose override
+
+Using a [override](https://docs.docker.com/compose/reference/overview/#specifying-multiple-compose-files)  
+ file named `docker-compose.override.yml` ensures that the production
+configuration remains untouched.
+
+As example, an override could look like this:
+
+```yml
+version: '3.4'
+ services:
+  php:
+    build:
+      args:
+        BUILD_ENV: dev
+    environment:
+      # See https://docs.docker.com/docker-for-mac/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host
+      # The `remote_host` below may optionally be replaced with `remote_connect_back`
+      #
+      # Choose some other port than `9000`, as this one is already occupied by FPM
+      # Make sure to also change your listening port in the IDE to this value
+      XDEBUG_CONFIG: remote_enable=1
+        remote_host=host.docker.internal
+        remote_port=9999
+        idekey=PHPSTORM
+      # This should correspond to the server declared in PHPStorm `Preferences | Languages & Frameworks | PHP | Servers`
+      # Then PHPStorm will use the corresponding path mappings
+      PHP_IDE_CONFIG: serverName=api-platform
+```