ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-04-12 13:27:50 +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
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
12 changed files with 973 additions and 571 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/advanced/connect-to-host-os.rst
View File

@ -13,6 +13,7 @@ This section explains how to connect from inside a Devilbox container to the hos
.. contents:: :local:
Prerequisites
=============
@ -66,6 +67,8 @@ Docker 17.06.0-ce+ and Docker compose 1.14.0+
CNAME: ``docker.for.mac.localhost``
.. _connect_to_host_os_docker_for_win:
Docker for Windows
==================

410
docs/intermediate/configure-php-xdebug.rst
View File

@ -4,12 +4,7 @@
Configure PHP Xdebug
********************
This tutorial shows you how to enable and use Xdebug with the Devilbox.
.. seealso::
If you are unsure of how to add custom ``*.ini`` files to the Devilbox,
have a look at this section first: :ref:`php_ini`
This section explains in depth how to enable and use PHP Xdebug with the Devilbox.
**Table of Contents**
@ -17,182 +12,59 @@ This tutorial shows you how to enable and use Xdebug with the Devilbox.
.. contents:: :local:
.. _configure_php_xdebug_enable_xdebug:
Introduction
============
Enable Xdebug
=============
In order to have a working Xdebug, you need to ensure two things:
This section shows you the minimum required ``*.ini`` ini settings to get xdebug to work with
the Devilbox. It will also highlight the differences between operating system and Docker versions.
1. **PHP Xdebug** must be configured and enabled in PHP itself
2. Your **IDE/editor** must be configured and requires a way talk to PHP
.. seealso:: See here for how to add the ``*.ini`` values to the Devilbox: :ref:`php_ini`.
Configuring PHP Xdebug will slightly differ when configuring it for a dockerized environment.
This is due to the fact that Docker versions on different host os have varying implementations of
how they connect back to the host.
Once you have configured Xdebug, you can verify it at the Devilbox intranet:
http://localhost/info_php.php
Most IDE or editors will also require different configurations for how they talk to PHP Xdebug.
This is at least most likely the case for ``xdebug.idekey``.
Required for all OS
-------------------
Configure PHP container for Xdebug
==================================
Additionally to the specific configurations for each operating system and Docker version you will
probably also want to add the following to your ini file:
.. toctree::
:glob:
:maxdepth: 1
:hidden:
.. code-block:: ini
:caption: xdebug.ini
/intermediate/configure-php-xdebug/php-xdebug-options
/intermediate/configure-php-xdebug/xdebug-*
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
The following gives you a step-by-step guide on how to setup PHP Xdebug for the Devilbox depending
on what host operating system you are using.
.. seealso:: https://xdebug.org/docs/all_settings
Be reminded that PHP configuration is always done per version, i.e. having it configured for
PHP 7.2, does not enable it for any other versions.
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.
For the sake of this tutorial we are going to use ``PHPSTORM`` as an example value.
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.
.. important::
You can set the value of ``xdebug.idekey`` to whatever you like, however it is important
to remember what value you have set. Throughout the examples in this tutorial it is assumed,
that the value is ``PHPSTORM``.
.. seealso::
* :ref:`configure_php_xdebug_options`
* :ref:`configure_php_xdebug_lin`
* :ref:`configure_php_xdebug_mac`
* :ref:`configure_php_xdebug_win`
* :ref:`configure_php_xdebug_docker_toolbox` (Mac or Windows)
Linux
-----
Configure your IDE/editor for Xdebug
====================================
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 1
After you have setup PHP Xdebug as referenced above, you can continue to configure your currently
used IDE/editor.
xdebug.remote_connect_back=1
MacOS (Docker for Mac)
----------------------
Docker 18.03.0-ce+ and Docker compose 1.20.1+
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 1
xdebug.remote_host=host.docker.internal
xdebug.remote_connect_back=0
Docker 17.12.0-ce+ and Docker compose 1.18.0+
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 1
xdebug.remote_host=docker.for.mac.host.internal
xdebug.remote_connect_back=0
Docker 17.06.0-ce+ and Docker compose 1.14.0+
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 1
xdebug.remote_host=docker.for.mac.localhost
xdebug.remote_connect_back=0
If you have older versions, upgrade.
MacOS (Docker Toolbox)
----------------------
.. warning::
This is a legacy solution, upgrade to Docker for Mac
https://docs.docker.com/toolbox
Windows (Docker for Windows)
----------------------------
Docker 18.03.0-ce+ and Docker compose 1.20.1+
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 1
xdebug.remote_host=docker.for.win.host.internal
xdebug.remote_connect_back=0
Docker 17.06.0-ce+ and Docker compose 1.14.0+
.. code-block:: ini
:caption: xdebug.ini
:emphasize-lines: 1
xdebug.remote_host=docker.for.win.host.localhost
xdebug.remote_connect_back=0
If you have older versions, upgrade.
Windows (Docker Toolbox)
------------------------
.. warning::
This is a legacy solution, upgrade to Docker for Windows
https://docs.docker.com/toolbox
Configure your IDE
==================
Required for all IDE
--------------------
Most IDE/editors will usually be configured in a very similar way, which comes down to two main
settings;
Path mapping
^^^^^^^^^^^^
------------
The path mapping is a mapping between the file path on your host operating system and the one
inside the PHP Docker container.
@ -207,205 +79,23 @@ The path inside the PHP Docker container is always ``/shared/httpd``.
you need to get the actualy absolute path of it, when setting up your IDE.
IDE key
^^^^^^^
-------
This is the value you have set in ``xdebug.ini`` for ``xdebug.idekey``. In the example of this
tutorial, the value was set to ``PHPSTORM``.
Port
^^^^
This is the value you have set in ``xdebug.ini`` for ``xdebug.remote_port``. In the example of this
tutorial, the value was set to ``9000``.
.. toctree::
:glob:
:maxdepth: 1
:hidden:
Atom
----
/intermediate/configure-php-xdebug/editor-*
1. Install `php-debug <https://atom.io/packages/php-debug>`_
2. Configure ``config.cson`` (File -> Config...)
3. Adjust your ``xdebug.ini``
Configuration
-------------
For Atom, you need to provide a different ``xdebug.idekey`` in your php.ini file ``xdebug.ini``:
.. code-block:: ini
:caption: xdebug.ini
xdebug.idekey=xdebug.atom
Linux
^^^^^^
.. code-block:: js
:caption: launch.json
:emphasize-lines: 6
"php-debug":
{
ServerPort: 9000
PathMaps: [
"remotepath;localpath"
"/shared/httpd;/home/cytopia/repo/devilbox/data/www"
]
}
MacOS (Docker for Mac)
^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
MacOS (Docker Toolbox)
^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
Windows (Docker for Windows)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
Windows (Docker Toolbox)
^^^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
PHPStorm
--------
Linux
^^^^^^
Enable Xdebug for the port set in ``xdebug.ini``:
.. include:: /_includes/figures/xdebug/phpstorm-settings.rst
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
Set DBGp proxy settings:
.. include:: /_includes/figures/xdebug/phpstorm-dbgp-proxy.rst
MacOS (Docker for Mac)
^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
MacOS (Docker Toolbox)
^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
Windows (Docker for Windows)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
Windows (Docker Toolbox)
^^^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
Sublime Text 3
--------------
1. Install `Xdebug Client <https://github.com/martomo/SublimeTextXdebug>`_ via the Sublime Package Control.
2. Configure ``Xdebug.sublime-settings`` (Tools -> Xdebug -> Settings - User)
Linux
^^^^^^
.. 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
}
MacOS (Docker for Mac)
^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
MacOS (Docker Toolbox)
^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
Windows (Docker for Windows)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
Windows (Docker Toolbox)
^^^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
Visual Studio Code
------------------
1. Install `vscode-php-debug <https://github.com/felixfbecker/vscode-php-debug>`_
2. Configure ``launch.json``
Linux
^^^^^^
.. 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
}
]
}
MacOS (Docker for Mac)
^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
MacOS (Docker Toolbox)
^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
Windows (Docker for Windows)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
Windows (Docker Toolbox)
^^^^^^^^^^^^^^^^^^^^^^^^
.. todo:: Help needed. Please provide your config.
..
MacOS videos
https://serversforhackers.com/c/getting-xdebug-working
https://serversforhackers.com/c/auto-config
https://www.arroyolabs.com/2016/10/docker-xdebug/
https://medium.com/@yuliakostrikova/configure-remote-debugging-with-xdebug-for-php-docker-container-on-macos-8edbc01dc373
https://github.com/petronetto/php7-alpine
#old
docker.for.mac.localhost
#new
docker.for.mac.host.internal
docker.for.win.localhost
.. 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`

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.