diff --git a/docs/advanced/connect-to-host-os.rst b/docs/advanced/connect-to-host-os.rst index cf85fba6..318474ea 100644 --- a/docs/advanced/connect-to-host-os.rst +++ b/docs/advanced/connect-to-host-os.rst @@ -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 ================== diff --git a/docs/intermediate/configure-php-xdebug.rst b/docs/intermediate/configure-php-xdebug.rst index 8a2d75b4..d8354993 100644 --- a/docs/intermediate/configure-php-xdebug.rst +++ b/docs/intermediate/configure-php-xdebug.rst @@ -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 `_). 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 `_ -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 `_ 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 `_ -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` diff --git a/docs/intermediate/configure-php-xdebug/atom.rst b/docs/intermediate/configure-php-xdebug/atom.rst deleted file mode 100644 index 038178ed..00000000 --- a/docs/intermediate/configure-php-xdebug/atom.rst +++ /dev/null @@ -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 `_ 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` diff --git a/docs/intermediate/configure-php-xdebug/editor-atom.rst b/docs/intermediate/configure-php-xdebug/editor-atom.rst new file mode 100644 index 00000000..8877ded0 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/editor-atom.rst @@ -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 `_ + +**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``. diff --git a/docs/intermediate/configure-php-xdebug/editor-phpstorm.rst b/docs/intermediate/configure-php-xdebug/editor-phpstorm.rst new file mode 100644 index 00000000..74213037 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/editor-phpstorm.rst @@ -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 diff --git a/docs/intermediate/configure-php-xdebug/editor-sublime3.rst b/docs/intermediate/configure-php-xdebug/editor-sublime3.rst new file mode 100644 index 00000000..d0f6544c --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/editor-sublime3.rst @@ -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 `_ + +**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! diff --git a/docs/intermediate/configure-php-xdebug/editor-vscode.rst b/docs/intermediate/configure-php-xdebug/editor-vscode.rst new file mode 100644 index 00000000..075f94e1 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/editor-vscode.rst @@ -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 `_ + +**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! diff --git a/docs/intermediate/configure-php-xdebug/php-xdebug-options.rst b/docs/intermediate/configure-php-xdebug/php-xdebug-options.rst new file mode 100644 index 00000000..cd952329 --- /dev/null +++ b/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 `_). 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. diff --git a/docs/intermediate/configure-php-xdebug/xdebug-docker-toolbox.rst b/docs/intermediate/configure-php-xdebug/xdebug-docker-toolbox.rst new file mode 100644 index 00000000..aaf4a191 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/xdebug-docker-toolbox.rst @@ -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. diff --git a/docs/intermediate/configure-php-xdebug/xdebug-lin.rst b/docs/intermediate/configure-php-xdebug/xdebug-lin.rst new file mode 100644 index 00000000..895490ea --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/xdebug-lin.rst @@ -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. diff --git a/docs/intermediate/configure-php-xdebug/xdebug-mac.rst b/docs/intermediate/configure-php-xdebug/xdebug-mac.rst new file mode 100644 index 00000000..2767500d --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/xdebug-mac.rst @@ -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. diff --git a/docs/intermediate/configure-php-xdebug/xdebug-win.rst b/docs/intermediate/configure-php-xdebug/xdebug-win.rst new file mode 100644 index 00000000..5095ca56 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/xdebug-win.rst @@ -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.