Merge pull request #96 from silinternational/feature/remote-debug

install xdebug for remote debugging

Author: briskt

README.md

@@ -232,3 +232,28 @@ Translations are categorized by page in definition files located in the `diction
 Localization is affected by the configuration setting `language.available`. Only language codes found in this property will be utilized.  
 For example, if a translation is provided in Afrikaans for this module, the configuration must be adjusted to make 'af' an available
 language. If that's not done, the translation function will not utilize the translations even if provided.
+
+### Debugging
+
+Xdebug can be enabled by doing the following:
+
+1. Define `REMOTE_DEBUG_IP` in `local.env`. This should be the IP address of your development machine, i.e. the one that
+   is running your IDE. If you're using Linux as your Docker host, you can use 172.17.0.1 here.
+2. Map run-debug.sh into the container you wish to debug. For example:
+```yaml
+    volumes:
+      - ./development/run-debug.sh:/data/run.sh
+```
+3. Enable debugging in your IDE. See the next section for PhpStorm setup.
+
+## Configuring PhpStorm for remote debugging
+
+In PhpStorm go to: Preferences > PHP > Debug > DBGp Proxy and set the following settings:
+- Host: (your IP address or hostname)
+- Port: 9000
+  
+Set path mappings in: Preferences > PHP > Servers
+- Add a server and map the project folder to '/data/vendor/simplesamlphp/simplesamlphp/modules/material'
+- Map other directories as needed. PhpStorm should prompt when an unrecognized path is encountered.
+
+Then start listening by clicking the "listen" button on the PhpStorm toolbar.

development/run-debug.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+set -x
+
+# establish a signal handler to catch the SIGTERM from a 'docker stop'
+# reference: https://medium.com/@gchudnov/trapping-signals-in-docker-containers-7a57fdda7d86
+term_handler() {
+  apache2ctl stop
+  exit 143; # 128 + 15 -- SIGTERM
+}
+trap 'kill ${!}; term_handler' SIGTERM
+
+export XDEBUG_CONFIG="remote_enable=1 remote_host="$REMOTE_DEBUG_IP
+
+apt-get update
+apt-get install php-xdebug
+
+cd /data
+
+# Send info about this image's O/S and PHP version to our logs.
+cat /etc/*release | grep PRETTY
+php -v | head -n 1
+
+apache2ctl -k start -D FOREGROUND
+
+# endless loop with a wait is needed for the trap to work
+while true
+do
+  tail -f /dev/null & wait ${!}
+done

local.env.dist

@@ -10,3 +10,5 @@ MFA_U2F_appId=
 ### Optional ENV vars ###
 LOGENTRIES_KEY=
 COMPOSER_AUTH=
+
+REMOTE_DEBUG_IP=