#250 PHP Xdebug documentation

docs/intermediate/configure-php-xdebug/php-xdebug-options.rst

@@ -0,0 +1,80 @@
+:orphan:
+
+.. include:: /_includes/all.rst
+
+.. _configure_php_xdebug_options:
+
+************************
+Xdebug options explained
+************************
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Example
+=======
+
+Consider the following ``xdebug.ini`` as an example:
+
+.. code-block:: ini
+   :caption: xdebug.ini
+
+   xdebug.default_enable=1
+   xdebug.remote_enable=1
+   xdebug.remote_handler=dbgp
+   xdebug.remote_port=9000
+   xdebug.remote_autostart=1
+   xdebug.idekey="PHPSTORM"
+   xdebug.remote_log=/var/log/php/xdebug.log
+
+.. seealso:: https://xdebug.org/docs/all_settings
+
+default_enable
+--------------
+By enabling this, stacktraces will be shown by default on an error event.
+It is advisable to leave this setting set to 1.
+
+remote_enable
+-------------
+This switch controls whether Xdebug should try to contact a debug client which is listening on the
+host and port as set with the settings ``xdebug.remote_host`` and ``xdebug.remote_port``.
+If a connection can not be established the script will just continue as if this setting was 0.
+
+remote_handler
+--------------
+Can be either ``'php3'`` which selects the old PHP 3 style debugger output, ``'gdb'`` which enables
+the GDB like debugger interface or ``'dbgp'`` - the debugger protocol. The DBGp protocol is the only
+supported protocol.
+
+**Note:** Xdebug 2.1 and later only support ``'dbgp'`` as protocol.
+
+remote_port
+-----------
+The port to which Xdebug tries to connect on the remote host. Port ``9000`` is the default for both
+the client and the bundled debugclient. As many clients use this port number, it is best to leave
+this setting unchanged.
+
+remote_autostart
+----------------
+Normally you need to use a specific HTTP GET/POST variable to start remote debugging (see
+`Remote Debugging <https://xdebug.org/docs/remote#browser_session>`_). When this setting is set to
+``1``, Xdebug will always attempt to start a remote debugging session and try to connect to a client,
+even if the GET/POST/COOKIE variable was not present.
+
+idekey
+------
+Controls which IDE Key Xdebug should pass on to the DBGp debugger handler. The default is based on
+environment settings. First the environment setting DBGP_IDEKEY is consulted, then USER and as last
+USERNAME. The default is set to the first environment variable that is found. If none could be found
+the setting has as default ''. If this setting is set, it always overrides the environment variables.
+
+.. important::
+   Many IDE/editors require a specific value for ``xdebug.idekey``. Make sure you pay
+   special attention to that variable when it comes to configuring your IDE/editor.
+
+remote_log
+----------
+Keep the exact path of ``/var/log/php/xdebug.log``. You will then have the log file available
+in the Devilbox log directory of the PHP version for which you have configured Xdebug.