ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-06-17 22:58:20 +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

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`