ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-06-15 05:38:17 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

#250 PHP Xdebug documentation

Browse Source
This commit is contained in:
cytopia
2018-07-23 23:25:48 +02:00
parent b48a7a393f
commit ce56d52dd1
12 changed files with 973 additions and 571 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
docs/intermediate/configure-php-xdebug/atom.rst
View File

@ -1,211 +0,0 @@
:orphan:
.. include:: /_includes/all.rst
.. _configure_php_xdebug_atom:
*************************
Configure Xdebug for Atom
*************************
**Table of Contents**
.. contents:: :local:
Prerequisites
=============
Ensure you know how to customize ``php.ini`` values for the Devilbox and Xdebug is enabled.
.. seealso::
* :ref:`php_ini`
* :ref:`configure_php_xdebug_enable_xdebug`
Atom configuration
==================
1. Install `php-debug <https://atom.io/packages/php-debug>`_ for Atom
2. Configure path mapping in ``config.cson`` or ui.
.. code-block:: js
:caption: launch.json
:emphasize-lines: 6
"php-debug":
{
ServerPort: 9000
PathMaps: [
"remotepath;localpath"
"/shared/httpd;/home/cytopia/repo/devilbox/data/www"
]
}
.. important::
You need to adjust the path part on the right side, as it will most likely be different
on your system.
Also note that on Windows you have to use ``\\`` as directory separators.
E.g.: ``C:\\Users\\projects``.
Xdebug configuration
====================
Xdebug configuration for the Devilbox will slightly vary depending on your host operating system
and your Docker version (native or Toolbox). Pick your system below and create correct
``xdebug.ini`` for the Devilbox.
Docker on Linux
---------------
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6,10
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The Linux way
xdebug.remote_connect_back=1
# idekey value is specific to each editor
# Verify with Atom documentation
xdebug.idekey=xdebug-atom
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
Docker for Mac
--------------
Via host alias address
^^^^^^^^^^^^^^^^^^^^^^
.. important::
Ensure you have created an :ref:`howto_host_address_alias_on_mac` and
``10.254.254.254`` is aliased to your localhost.
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6-7,11
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The MacOS way (host alias)
xdebug.remote_connect_back=0
xdebug.remote_host=10.254.254.254
# idekey value is specific to each editor
# Verify with Atom documentation
xdebug.idekey=xdebug-atom
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
Via CNAME alias
^^^^^^^^^^^^^^^
Docker for Mac received many default CNAMEs throughout its versions. The most recent and active
is ``host.docker.internal``. So instead of creating an host alias, you could also try if the CNAME
is a working solution:
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6-7,11
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The MacOS way (CNAME)
xdebug.remote_connect_back=0
xdebug.remote_host=host.docker.internal
# idekey value is specific to each editor
# Verify with Atom documentation
xdebug.idekey=xdebug-atom
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
.. seealso:: CNAME for :ref:`connect_to_host_os_docker_for_mac`
Docker for Windows
------------------
On Windows you will have to manually gather the IP address and add it to ``xdebug.remote_host``.
1. Open command line
2. Enter ``ipconfig``
3. Look for the IP4 address in ``DockerNAT`` (e.g.: ``192.168.246.1``)
.. seealso:: :ref:`howto_open_terminal_on_win`
.. important::
The below listed ``xdebug.ini`` uses ``192.168.246.1``, you need to change this to whatever
IP address came out on your system.
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6-7,11
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The Windows way
xdebug.remote_connect_back=0
xdebug.remote_host=192.168.246.1
# idekey value is specific to each editor
# Verify with Atom documentation
xdebug.idekey=xdebug-atom
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
Docker Toolbox
--------------
.. note:: This applies for both, Docker Toolbox on MacOS and Docker Toolbox on Windows.
1. Forward host os port ``9000`` (Xdebug listening port of your IDE) to Docker Toolbox machine also on port ``9000``.
(remote or local forward)
.. seealso::
* :ref:`howto_ssh_port_forward_on_docker_toolbox_from_host`
* :ref:`howto_ssh_port_forward_on_host_to_docker_toolbox`
2. Add ``xdebug.php``
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6-7,11
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The Docker Toolbox way
xdebug.remote_connect_back=0
xdebug.remote_host=docker.for.lin.host.internal
# idekey value is specific to each editor
# Verify with Atom documentation
xdebug.idekey=xdebug-atom
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
.. seealso::
* CNAME for :ref:`connect_to_host_os_docker_on_linux`

74
docs/intermediate/configure-php-xdebug/editor-atom.rst Normal file
View File

@ -0,0 +1,74 @@
:orphan:
.. include:: /_includes/all.rst
.. _configure_php_xdebug_editor_atom:
*************************
Configure Xdebug for Atom
*************************
**Table of Contents**
.. contents:: :local:
Prerequisites
=============
Ensure that ``xdebug.idekey`` is set to ``xdebug.atom`` in your PHP Xdebug configuration.
.. seealso::
* :ref:`configure_php_xdebug_lin`
* :ref:`configure_php_xdebug_mac`
* :ref:`configure_php_xdebug_win`
* :ref:`configure_php_xdebug_docker_toolbox`
Assumption
==========
For the sake of this example, we will assume the following paths:
+------------------------------+------------------------------------------+
| Directory | Path |
+==============================+==========================================+
| Devilbox git directory | ``/home/cytopia/repo/devilbox`` |
+------------------------------+------------------------------------------+
| :ref:`env_httpd_datadir` | ``./data/www`` |
+------------------------------+------------------------------------------+
| Resulting local project path | ``/home/cytopia/repo/devilbox/data/www`` |
+------------------------------+------------------------------------------+
The **Resulting local project path** is the path where all projects are stored locally on your
host operating system. No matter what this path is, the equivalent remote path (inside the Docker
container) is always ``/shared/httpd``.
.. important:: Remember this, when it comes to path mapping in your IDE/editor configuration.
Configuration
=============
**1. Install php-debug for Atom**
.. seealso:: `php-debug <https://atom.io/packages/php-debug>`_
**2. Configure path mapping in config.cson or ui**
.. code-block:: js
:caption: config.cson
:emphasize-lines: 6
"php-debug":
{
ServerPort: 9000
PathMaps: [
"remotepath;localpath"
"/shared/httpd;/home/cytopia/repo/devilbox/data/www"
]
}
.. important::
On Windows you have to use ``\\`` as directory separators for the local path mapping.
E.g.: ``C:\\Users\\projects``.

69
docs/intermediate/configure-php-xdebug/editor-phpstorm.rst Normal file
View File

@ -0,0 +1,69 @@
:orphan:
.. include:: /_includes/all.rst
.. _configure_php_xdebug_editor_phpstorm:
*****************************
Configure Xdebug for PhpStorm
*****************************
**Table of Contents**
.. contents:: :local:
Prerequisites
=============
Ensure that ``xdebug.idekey`` is set to ``PHPSTORM`` in your PHP Xdebug configuration.
.. seealso::
* :ref:`configure_php_xdebug_lin`
* :ref:`configure_php_xdebug_mac`
* :ref:`configure_php_xdebug_win`
* :ref:`configure_php_xdebug_docker_toolbox`
Assumption
==========
For the sake of this example, we will assume the following paths:
+------------------------------+------------------------------------------+
| Directory | Path |
+==============================+==========================================+
| Devilbox git directory | ``/home/cytopia/repo/devilbox`` |
+------------------------------+------------------------------------------+
| :ref:`env_httpd_datadir` | ``./data/www`` |
+------------------------------+------------------------------------------+
| Resulting local project path | ``/home/cytopia/repo/devilbox/data/www`` |
+------------------------------+------------------------------------------+
The **Resulting local project path** is the path where all projects are stored locally on your
host operating system. No matter what this path is, the equivalent remote path (inside the Docker
container) is always ``/shared/httpd``.
.. important:: Remember this, when it comes to path mapping in your IDE/editor configuration.
Configuration
=============
**1. Ensure Xdebug port is set to 9000**
.. include:: /_includes/figures/xdebug/phpstorm-settings.rst
**2. Set path mapping**
Create a new PHP server and set a path mapping. This tutorial assumes your local Devilbox projects
to be in ``./data/www`` of the Devilbox git directory:
.. include:: /_includes/figures/xdebug/phpstorm-path-mapping.rst
.. important::
Recall the path mapping!
**3. Ensure DBGp proxy settings are configured**
.. include:: /_includes/figures/xdebug/phpstorm-dbgp-proxy.rst

79
docs/intermediate/configure-php-xdebug/editor-sublime3.rst Normal file
View File

@ -0,0 +1,79 @@
:orphan:
.. include:: /_includes/all.rst
.. _configure_php_xdebug_editor_sublime3:
***********************************
Configure Xdebug for Sublime Text 3
***********************************
**Table of Contents**
.. contents:: :local:
Prerequisites
=============
Ensure that ``xdebug.idekey`` is set to ``PHPSTORM`` in your PHP Xdebug configuration.
.. seealso::
* :ref:`configure_php_xdebug_lin`
* :ref:`configure_php_xdebug_mac`
* :ref:`configure_php_xdebug_win`
* :ref:`configure_php_xdebug_docker_toolbox`
Assumption
==========
For the sake of this example, we will assume the following paths:
+------------------------------+------------------------------------------+
| Directory | Path |
+==============================+==========================================+
| Devilbox git directory | ``/home/cytopia/repo/devilbox`` |
+------------------------------+------------------------------------------+
| :ref:`env_httpd_datadir` | ``./data/www`` |
+------------------------------+------------------------------------------+
| Resulting local project path | ``/home/cytopia/repo/devilbox/data/www`` |
+------------------------------+------------------------------------------+
The **Resulting local project path** is the path where all projects are stored locally on your
host operating system. No matter what this path is, the equivalent remote path (inside the Docker
container) is always ``/shared/httpd``.
.. important:: Remember this, when it comes to path mapping in your IDE/editor configuration.
Configuration
=============
**1. Install Xdebug Client**
Use Sublime's Package Control to search for and install ``Xdebug Client``.
.. seealso:: `Xdebug Client <https://github.com/martomo/SublimeTextXdebug>`_
**2. Configure Xdebug.sublime-settings**
* Navigate to ``Tools`` -> ``Xdebug`` -> ``Settings - User`` in the menu
* This will open the configuration file in Sublime
.. code-block:: json
:caption: Xdebug-sublime-settings
:emphasize-lines: 3,6
{
"path_mapping": {
"/shared/httpd" : "/home/cytopia/repo/devilbox/data/www"
},
"url": "",
"ide_key": "PHPSTORM",
"host": "0.0.0.0",
"port": 9000
}
.. important::
Recall the path mapping!

86
docs/intermediate/configure-php-xdebug/editor-vscode.rst Normal file
View File

@ -0,0 +1,86 @@
:orphan:
.. include:: /_includes/all.rst
.. _configure_php_xdebug_editor_vscode:
***************************************
Configure Xdebug for Visual Studio Code
***************************************
**Table of Contents**
.. contents:: :local:
Prerequisites
=============
Ensure that ``xdebug.idekey`` is set to ``PHPSTORM`` in your PHP Xdebug configuration.
.. seealso::
* :ref:`configure_php_xdebug_lin`
* :ref:`configure_php_xdebug_mac`
* :ref:`configure_php_xdebug_win`
* :ref:`configure_php_xdebug_docker_toolbox`
Assumption
==========
For the sake of this example, we will assume the following paths:
+------------------------------+------------------------------------------+
| Directory | Path |
+==============================+==========================================+
| Devilbox git directory | ``/home/cytopia/repo/devilbox`` |
+------------------------------+------------------------------------------+
| :ref:`env_httpd_datadir` | ``./data/www`` |
+------------------------------+------------------------------------------+
| Resulting local project path | ``/home/cytopia/repo/devilbox/data/www`` |
+------------------------------+------------------------------------------+
The **Resulting local project path** is the path where all projects are stored locally on your
host operating system. No matter what this path is, the equivalent remote path (inside the Docker
container) is always ``/shared/httpd``.
.. important:: Remember this, when it comes to path mapping in your IDE/editor configuration.
Configuration
=============
**1. Install vscode-php-debug**
.. seealso:: `vscode-php-debug <https://github.com/felixfbecker/vscode-php-debug>`_
**2. Configure launch.json**
.. code-block:: json
:caption: launch.json
:emphasize-lines: 9,10
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xbebug",
"type": "php",
"request": "launch",
"port": 9000,
"serverSourceRoot": "/shared/httpd",
"localSourceRoot": "/home/cytopia/repo/devilbox/data/www"
}, {
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",
"port": 9000
}
]
}
.. important::
Recall the path mapping!

80
docs/intermediate/configure-php-xdebug/php-xdebug-options.rst Normal file
View File

@ -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.

99
docs/intermediate/configure-php-xdebug/xdebug-docker-toolbox.rst Normal file
View File

@ -0,0 +1,99 @@
:orphan:
.. include:: /_includes/all.rst
.. _configure_php_xdebug_docker_toolbox:
********************************
Configure Xdebug: Docker Toolbox
********************************
Docker Toolbox regardless of running on MacOS or Windows requires an additional port-forward
from your host operating system to the Docker Toolbox machine.
**Table of Contents**
.. contents:: :local:
Prerequisites
=============
Ensure you know how to customize ``php.ini`` values for the Devilbox.
.. seealso::
* :ref:`php_ini`
* :ref:`configure_php_xdebug_options`
Configure php.ini
=================
The following example show how to configure PHP Xdebug for PHP 5.6:
**1. Forward host port 9000 to Docker Toolbox machine**
Your IDE/editor will open up port ``9000`` on your host operating system. PHP Xdebug requires
this port to connect to in order to send Xdebug events.
As Docker Toolbox itself runs in a virtual machine, you need to forward traffic from the same
port in that virtual machine back to your host operating system.
.. seealso::
* :ref:`howto_ssh_port_forward_on_docker_toolbox_from_host`
* :ref:`howto_ssh_port_forward_on_host_to_docker_toolbox`
**2. Create xdebug.ini**
.. code-block:: bash
# Navigate to the Devilbox git directory
host> cd path/to/devilbox
# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/
# Create and open debug.ini file
host> vi xdebug.ini
**3. Paste the following content into xdebug.ini**
Once the por-forward is up, the configuration matches the one for Docker on Linux
.. seealso::
* CNAME for :ref:`connect_to_host_os_docker_on_linux`
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6-7,11
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The Docker Toolbox way
xdebug.remote_connect_back=0
xdebug.remote_host=docker.for.lin.host.internal
# idekey value is specific to each editor
# Verify with your IDE/editor documentation
xdebug.idekey=PHPSTORM
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
**4. Configure your IDE/editor**
.. seealso::
* :ref:`configure_php_xdebug_editor_atom`
* :ref:`configure_php_xdebug_editor_phpstorm`
* :ref:`configure_php_xdebug_editor_sublime3`
* :ref:`configure_php_xdebug_editor_vscode`
.. important::
Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above
configured ``xdebug.ini``.
**5. Restart the Devilbox**
Restarting the Devilbox is important in order for it to read the new PHP settings.

85
docs/intermediate/configure-php-xdebug/xdebug-lin.rst Normal file
View File

@ -0,0 +1,85 @@
:orphan:
.. include:: /_includes/all.rst
.. _configure_php_xdebug_lin:
*********************************
Configure Xdebug: Docker on Linux
*********************************
Docker on Linux allows Xdebug to automatically connect back to the host system without the need
of an explicit IP address.
**Table of Contents**
.. contents:: :local:
Prerequisites
=============
Ensure you know how to customize ``php.ini`` values for the Devilbox.
.. seealso::
* :ref:`php_ini`
* :ref:`configure_php_xdebug_options`
Configure php.ini
=================
Configuring Xdebug for Docker on Linux is straight forward and you must only pay attention to
two variables highlighted below.
The following example show how to configure PHP Xdebug for PHP 5.6:
**1. Create xdebug.ini**
.. code-block:: bash
# Navigate to the Devilbox git directory
host> cd path/to/devilbox
# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/
# Create and open debug.ini file
host> vi xdebug.ini
**2. Paste the following content into xdebug.ini**
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6,10
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The Linux way
xdebug.remote_connect_back=1
# idekey value is specific to each editor
# Verify with your IDE/editor documentation
xdebug.idekey=PHPSTORM
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
**3. Configure your IDE/editor**
.. seealso::
* :ref:`configure_php_xdebug_editor_atom`
* :ref:`configure_php_xdebug_editor_phpstorm`
* :ref:`configure_php_xdebug_editor_sublime3`
* :ref:`configure_php_xdebug_editor_vscode`
.. important::
Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above
configured ``xdebug.ini``.
**4. Restart the Devilbox**
Restarting the Devilbox is important in order for it to read the new PHP settings.

173
docs/intermediate/configure-php-xdebug/xdebug-mac.rst Normal file
View File

@ -0,0 +1,173 @@
:orphan:
.. include:: /_includes/all.rst
.. _configure_php_xdebug_mac:
********************************
Configure Xdebug: Docker for Mac
********************************
Docker for MacOS requires a well known IP address in order to connect to the host operating system.
This can be achieved with two different approaches described below.
.. seealso:: https://forums.docker.com/t/ip-address-for-xdebug/10460/32
**Table of Contents**
.. contents:: :local:
Prerequisites
=============
Ensure you know how to customize ``php.ini`` values for the Devilbox and Xdebug is enabled.
.. seealso::
* :ref:`php_ini`
* :ref:`configure_php_xdebug_options`
Configure php.ini: CNAME alias
==============================
**Option 1:** This option is the easiest to setup, but was also very fragile on many Docker versions.
Docker for Mac received many default CNAMEs throughout its versions. The most recent and active
one is ``host.docker.internal``. Use this CNAME as the remote address for Xdebug to connect to your
IDE/editor on your host os.
.. seealso::
CNAME for :ref:`connect_to_host_os_docker_for_mac`
In case ``host.docker.internal`` is not resolvable, read on here for alternative CNAME's
on Docker for Mac
.. important::
Before you try this approach, verify that the PHP Docker container is actually able to resolve
``host.docker.internal``:
.. code-block:: bash
host> cd path/to/devilbox
host> ./shell.sh
php> ping host.docker.internal
In case it is not resolvable, stick to the host alias address approach.
The following example show how to configure PHP Xdebug for PHP 5.6:
**1. Create xdebug.ini**
.. code-block:: bash
# Navigate to the Devilbox git directory
host> cd path/to/devilbox
# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/
# Create and open debug.ini file
host> vi xdebug.ini
**2. Paste the following content into xdebug.ini**
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6-7,11
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The MacOS way (CNAME)
xdebug.remote_connect_back=0
xdebug.remote_host=host.docker.internal
# idekey value is specific to each editor
# Verify IDE/editor documentation
xdebug.idekey=PHPSTORM
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
**3. Configure your IDE/editor**
.. seealso::
* :ref:`configure_php_xdebug_editor_atom`
* :ref:`configure_php_xdebug_editor_phpstorm`
* :ref:`configure_php_xdebug_editor_sublime3`
* :ref:`configure_php_xdebug_editor_vscode`
.. important::
Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above
configured ``xdebug.ini``.
**4. Restart the Devilbox**
Restarting the Devilbox is important in order for it to read the new PHP settings.
Configure php.ini: Host alias
=============================
**Option 2:** This is the most general option that should work with any Docker version on MacOS,
it does however require a few changes in your system.
.. important::
Ensure you have created an :ref:`howto_host_address_alias_on_mac` and
``10.254.254.254`` is aliased to your localhost.
The following example show how to configure PHP Xdebug for PHP 5.6:
**1. Create xdebug.ini**
.. code-block:: bash
# Navigate to the Devilbox git directory
host> cd path/to/devilbox
# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/
# Create and open debug.ini file
host> vi xdebug.ini
**2. Paste the following content into xdebug.ini**
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6-7,11
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The MacOS way (host alias)
xdebug.remote_connect_back=0
xdebug.remote_host=10.254.254.254
# idekey value is specific to each editor
# Verify with your IDE/editor documentation
xdebug.idekey=PHPSTORM
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
**3. Configure your IDE/editor**
.. seealso::
* :ref:`configure_php_xdebug_editor_atom`
* :ref:`configure_php_xdebug_editor_phpstorm`
* :ref:`configure_php_xdebug_editor_sublime3`
* :ref:`configure_php_xdebug_editor_vscode`
.. important::
Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above
configured ``xdebug.ini``.
**4. Restart the Devilbox**
Restarting the Devilbox is important in order for it to read the new PHP settings.

175
docs/intermediate/configure-php-xdebug/xdebug-win.rst Normal file
View File

@ -0,0 +1,175 @@
:orphan:
.. include:: /_includes/all.rst
.. _configure_php_xdebug_win:
************************************
Configure Xdebug: Docker for Windows
************************************
Docker for Windows requires a well known IP address in order to connect to the host operating system.
This can be achieved with two different approaches described below.
**Table of Contents**
.. contents:: :local:
Prerequisites
=============
Ensure you know how to customize ``php.ini`` values for the Devilbox and Xdebug is enabled.
.. seealso::
* :ref:`php_ini`
* :ref:`configure_php_xdebug_options`
Configure php.ini: CNAME alias
==============================
**Option 1:** This option is the easiest to setup, but was also very fragile on many Docker versions.
Docker for Windows received many default CNAMEs throughout its versions. The most recent and active
one is ``host.docker.internal``. Use this CNAME as the remote address for Xdebug to connect to your
IDE/editor on your host os.
.. seealso::
CNAME for :ref:`connect_to_host_os_docker_for_win`
In case ``host.docker.internal`` is not resolvable, read on here for alternative CNAME's
on Docker for Windows
.. important::
Before you try this approach, verify that the PHP Docker container is actually able to resolve
``host.docker.internal``:
.. code-block:: bash
C:\> cd path\to\devilbox
C:\> shell.bat
php> ping host.docker.internal
In case it is not resolvable, stick to the host alias address approach.
The following example show how to configure PHP Xdebug for PHP 5.6:
**1. Create xdebug.ini**
1. Navigate to the Devilbox directory
2. Navigate to ``cfg\php-ini-5.6\`` directory
3. Create a new file named ``xdebug.ini``
.. important::
Pay attention that windows is not adding ``.txt`` as a file extension.
**2. Paste the following content into xdebug.ini**
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6-7,11
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The Windows way (CNAME)
xdebug.remote_connect_back=0
xdebug.remote_host=host.docker.internal
# idekey value is specific to each editor
# Verify IDE/editor documentation
xdebug.idekey=PHPSTORM
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
**3. Configure your IDE/editor**
.. seealso::
* :ref:`configure_php_xdebug_editor_atom`
* :ref:`configure_php_xdebug_editor_phpstorm`
* :ref:`configure_php_xdebug_editor_sublime3`
* :ref:`configure_php_xdebug_editor_vscode`
.. important::
Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above
configured ``xdebug.ini``.
**4. Restart the Devilbox**
Restarting the Devilbox is important in order for it to read the new PHP settings.
Configure php.ini: Get IP manually
==================================
**Option 2:** This is the most general option that should work with any Docker version on Windows.
it does however require a small manual step.
The following example show how to configure PHP Xdebug for PHP 5.6:
**1. Gather IP address for Xdebug**
On Windows you will have to manually gather the IP address and add it to ``xdebug.remote_host``.
1. Open command line
2. Enter ``ipconfig``
3. Look for the IP4 address in ``DockerNAT`` (e.g.: ``192.168.246.1``)
.. seealso:: :ref:`howto_open_terminal_on_win`
.. important::
``192.168.246.1`` is meant as an example and will eventually differ on your system.
Ensure you substitute it with the correct IP address.
**2. Create xdebug.ini**
1. Navigate to the Devilbox directory
2. Navigate to ``cfg\php-ini-5.6\`` directory
3. Create a new file named ``xdebug.ini``
.. important::
Pay attention that windows is not adding ``.txt`` as a file extension.
**3. Paste the following content into xdebug.ini**
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 6-7,11
# Defaults
xdebug.remote_enable=1
xdebug.remote_port=9000
# The Windows way (IP address)
xdebug.remote_connect_back=0
xdebug.remote_host=192.168.246.1
# idekey value is specific to each editor
# Verify IDE/editor documentation
xdebug.idekey=PHPSTORM
# Optional: Set to true to auto-start xdebug
xdebug.remote_autostart=false
.. important::
``192.168.246.1`` is meant as an example and will eventually differ on your system.
Ensure you substitute it with the correct IP address.
**4. Configure your IDE/editor**
.. seealso::
* :ref:`configure_php_xdebug_editor_atom`
* :ref:`configure_php_xdebug_editor_phpstorm`
* :ref:`configure_php_xdebug_editor_sublime3`
* :ref:`configure_php_xdebug_editor_vscode`
.. important::
Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above
configured ``xdebug.ini``.
**5. Restart the Devilbox**
Restarting the Devilbox is important in order for it to read the new PHP settings.