Xdebug Docker For Mac

Posted on |



  • Next to 'PHP Interpreter' to bring up the interpreters. Choose 'Docker (SSH)' in the left pane and click on the little folder icon on the bottom of the window next to 'Configuration options'. In the pop up enter xdebug.remotehost as key and host.docker.internal as value and hit 'OK'.
  • XDebug for PHPUnit in Docker with PHPStorm. update Set the IP-address to the following DNS-name: docker.for.mac.localhost (yes, literally)!
  • Xdebug is an extension for PHP to assist with debugging and development. It contains a single step debugger to use with IDEs; it upgrades PHP's vardump function; it adds stack traces for Notices, Warnings, Errors and Exceptions; it features functionality for recording every function call and variable assignment to disk; it contains a profiler.

You'll want to expose port 9000, not bind. Also update your xdebug ini to the ip of your host (mac) not the ip of docker. I also added how you can mount the xdebug file from your mac directly to your docker so you can update it on the fly. This allows you more control since you may have to update your ip based of moving from wifi to wifi.

Xdebug is an extension for debugging your PHP code. Magento Cloud Docker provides a separate container to handle Xdebug requests in the Docker environment. Use this container to enable Xdebug and debug PHP code in your Docker environment without affecting your Magento Commerce Cloud project configuration.

The following instructions explain how to configure Xdebug and PhpStorm to debug in your local Docker environment.

If you use Microsoft Windows, take the following steps before continuing:

  1. Open your Docker settings.
  2. Select the Expose daemon on tcp://localhost:2375 without TLS checkbox.
  3. Wait for the settings to apply.

Enable Xdebug

  1. To enable Xdebug for your Docker environment, generate the Docker Compose configuration file in developer mode with the --with-xdebug option and any other required options, for example.

    This command adds the Xdebug configuration to your docker-compose.yml file.

  2. Follow the steps to launch the Docker environment in Developer mode.

    The default Docker environment configuration sets the following Xdebug configuration variables:

  3. Change any Xdebug configuration using the XDEBUG_CONFIG option. For example, to change the xdebug.remote_port option:

    On Linux systems, use the following command instead:

Docker xdebug phpstorm

To configure PhpStorm to work with Xdebug:

  1. In your PhpStorm project, open the settings panel.

    • Mac OS X—Select File > Preferences.
    • Windows/Linux—Select File > Settings.

  2. In the Settings panel, expand and locate the Languages & Frameworks > PHP > Servers section.

  3. Click the + to add a server configuration. The project name is in grey at the top.

  4. Configure the following settings for the new server configuration:

    • Name—Enter the name used for the serverName option from PHP_IDE_CONFIG value.
    • Host—Enter localhost.
    • Port—Enter 80.
    • Debugger—Select Xdebug.

  5. Select Use path mappings. In the File/Directory pane, the root of the project for the serverName displays.

  6. In the Absolute path on the server column, click and add a value to the MAGENTO_ROOT option. The default value is /app

  7. Change the Xdebug port to 9001 in the Languages & Frameworks > PHP > Debug > Xdebug > Debug Port panel.

  8. Click Apply.

Use Xdebug

The following steps describe debugging web requests and CLI commands.

To debug web requests:

  1. In your PhpStorm project, click (Start listening) in the top navigation bar.

  2. Add breakpoints in the pub/index.php file.

  3. Install the debug extension in the browser, and then click Debug to enable.

  4. In the browser, open the https://localhost URL.

  5. When PhpStorm recognizes the Xdebug connection, you can begin debugging web requests.

You can debug any Magento command or PHP script using the following steps.

To debug CLI commands:

  1. In your PhpStorm project, open the Build, Extension, Deployment > Docker panel, and then click + to add a new Docker server and update the following settings:

    • Name—Enter a name for the server, for example Docker Cloud.
    • Connect to Docker daemon with—
      • Windows—Select TCP socket and update Engine Api Url with tcp://localhost:2375.
      • Mac OS X—Select Docker for Mac. [default]

  2. In the Languages & Frameworks > PHP > Cli Interpreter panel, click […].

  3. Click [+] to add and configure a new Cli Interpreter from your Docker image. Update the following settings:

    • Name—Enter a name for the new interpreter, such as Magento cloud docker cli.
    • Remote—Select Docker.
      • Server—Select Docker Cloud from the previous step.
      • Image name—Select magento/magento-cloud-docker-php:7.x-cli.
    • Additional > Debugger extension—
      • Windows—Enter xdebug.
      • Mac OS X/Linux—Enter xdebug.so.
    • Click Refresh to verify that the interpreter and Xdebug extension are configured properly.

  4. Click Save.

  5. Open the Run/Debug Configuration window and add a new PHP script with the following settings:

    • Name—Enter bin/magento.
    • Configuration > File—Select the path to the bin/magento file in your local environment.

  6. Add breakpoints in the bin/magento file and the debug PHP script created in the previous step.

Using Xdebug Helper

You can install and use the Xdebug Helper Chrome extension to debug your PhP code from the browser.

To use Xdebug Helper with Chrome:

Xdebug Docker For Mac

  1. Install the Xdebug Helper extension from the Chrome store.

  2. Enable the extension in Chrome as shown in the following figure.

  3. Security applications for mac. In Chrome, click in the Chrome toolbar.

  4. From the Xdebug helper menu, click Options.

  5. From the IDE Key list, select PhpStorm.

  6. Click Save.

To use xdebug with macOS and docker is quite, let´s call it tricky ;)

The following steps need to be proceed to get it working:

  1. use the config from the xdebug.ini wihtin your docker web container. Important: set remote_connect_back to off

UPDATE

As mentioned by some comments (thanks for the feedback), it is not needed to configure the IP manually. Thus, the next step is optional and the configuration (xdebug.ini) is updated to use the dynamic IP.

  1. optional: set up an alias for your local interface (lo)
Docker

Hacks for mac. To bring up the alias at startup, you can either (sudo may be needed here):

  • manually place the file com.manuelselbach.docker_10254254254_alias.plist into directory: /Library/LaunchDaemons/

  • Or use the script set_and_install_autorun_alias_for_lo.sh

Configure PhpStorm

Docker Xdebug Phpstorm

After all that, just configure your PhpStorm:

  1. set port for xdebug Preferences -> Languages & Frameworks -> PHP -> Debug | Xdebug: Debug port = 9005
  2. configure a configuration in the toolbar
  • use PHP remote Debug
  • add a server to your domain (without protocoll like http:// or https://)
  • set port for http / https (not the xdebug port here)
  • select Debugger: Xdebug
  • if needed: set path mappings
  1. set Ide key (session id): to PHPSTORM

Docker Php Fpm Xdebug

Happy debugging with docker!