# Enabling XDebug

## Enabling XDebug in PHPStorm

### 1. Run Create Magento App in debug mode.

Use [start](https://docs.create-magento-app.com/v1/getting-started/available-commands/start) command with [debug](https://docs.create-magento-app.com/v1/getting-started/available-commands/start#d-debug) option to enable [XDebug](https://xdebug.org/).

{% hint style="danger" %}
Do not run the following command with the [-s option](https://docs.create-magento-app.com/v1/getting-started/available-commands/start#s-skip-setup)! CMA need to make adjustments to setup in debug mode!
{% endhint %}

```bash
yarn start --debug # for Yarn
npm run start -- --debug # for NPM
```

### 2. Setup PHPStorm

#### Set PHP CLI Interpreter

Go to **Settings > Languages & Frameworks > PHP** \
Here you need select correct CLI Interpreter for CMA project. CMA is currently using latest PHP 7.4 version so the path to PHP executable  should look like this: `$HOME/.phpbrew/php/php-7.4.13/bin/php` It should look like this:

![CLI Interpreters PHP configuration](https://3863794383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MOVnS5lKxiIvOL9no4d%2F-MP5XD9bFzf7x6s1SyMv%2F-MP5f6cd5Z_zGAro-Aer%2FScreenshot_20201221_210010.png?alt=media\&token=529b1c72-95ec-43bc-8c53-2e8a18662820)

#### Set XDebug port and other debugging configuration 

Go to **Settings > PHP > Debug** (in old PHPStorm: **Settings > Languages & Frameworks > PHP > Debug**) \
Make sure you have set debug port for XDebug to 9003,9111 (9003 is the default for XDebug 3 and port 9111 is used as a default for XDebug 2) and **Ignore external connections through the unregistered server configuration** is checked.

![](https://3863794383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MOVnS5lKxiIvOL9no4d%2F-MdrN6o1cx8IW-SQ8LsX%2F-MdrNFD-buAvTf1jH5LE%2FScreenshot_20210705_185435.png?alt=media\&token=8eccfd44-affe-463d-80f5-6fe60b9a7b0d)

#### Set Debug server configuration

Go to **Settings > Languages & Frameworks > PHP > Server**\
There you need to set up a debugging server for Create Magento App.\
Click +, use `http://localhost`  as **Host** value, put your Create Magento App running port as **Port** value, select **XDebug** as **Debugger** value.

{% hint style="info" %}
To find what your **Port** value is, use [status](https://docs.create-magento-app.com/v1/getting-started/available-commands/status) command.
{% endhint %}

![](https://3863794383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MOVnS5lKxiIvOL9no4d%2F-MgkQo_xafmG0TzEqiFD%2F-MgkRrqXEzZJSGAmWv0a%2FScreenshot_20210810_172430.png?alt=media\&token=ca808847-b366-45d5-a147-6e181db64d07)

Click **Apply** and close the window.

#### Set project debug configuration

Go to **Run > Edit Configurations**\
Click + and create new **PHP Remote Debug** configuration.\
Check **Filter debug connection by IDE key**, select your create-magento-app debug server as a **Server** value, use **PHPSTORM** as an **IDE Key** value.

![](https://3863794383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MOVnS5lKxiIvOL9no4d%2F-MgkQo_xafmG0TzEqiFD%2F-MgkSRETZn2nr2YB9NfB%2FScreenshot_20210810_172700.png?alt=media\&token=da1460d9-fffa-4f25-8ab2-4d4598a804a7)

Click **Apply** and close the window.

### 3. Prepare browser

You need to install [XDebug Helper](https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc) extension for Chrome to activate Debugging session in PHPStorm. \
After installation open extension **options** and select **IDE Key** value as **PHPStorm**.

Now when you open your CMA webpage you need to enable debug session by pressing **Debug** in extensions menu.

{% hint style="info" %}
This extension sets a cookie in your browser's requests: `XDEBUG_SESSION=PHPSTORM`. This cookie enables debugging in your browser.

Sometimes, you may want to enable debugging outside of the browser (for example, to debug individual GraphQL requests). You can also set `XDEBUG_SESSION=PHPSTORM` manually in the `Cookie` header. Most HTTP and GraphQL clients support this option.
{% endhint %}

### 4. Start debugging

Choose **create-magento-app** debug configuration in the top right corner of PHPStorm's window.

![](https://3863794383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MOVnS5lKxiIvOL9no4d%2F-MP5jTo3WmFiCnhFfdjk%2F-MP9paYlLVvTnpiCg1TC%2FScreenshot_20201222_162430.png?alt=media\&token=b7660f74-4b70-4e07-b4ac-860370b2ff19)

And after that pretty much everything is ready for PHP debugging.\
Click on **Start debugging** or press **Shift+F9**, put test breakpoint in **$project\_root/pub/index.php** file, reload the page and that is all!

Happy debugging!

## Enabling XDebug in VSCode

### 1. Run Create Magento App in debug mode.

Use [start](https://docs.create-magento-app.com/v1/getting-started/available-commands/start) command with [debug](https://docs.create-magento-app.com/v1/getting-started/available-commands/start#d-debug) option to enable [XDebug](https://xdebug.org/).

```bash
yarn start --debug # for Yarn
npm run start -- --debug # for NPM
```

### 2. Setup VSCode

Install [PHP Debug](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug) extension.

Then, create a file `launch.json` in `.vscode` folder at the root of your project if it does not exist.\
Inside that file add the following configuration:

```bash
{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "runtimeExecutable": "$HOME/.phpbrew/php/php-<php-version>/bin/php"
        }
    ]
}
```

Make sure to replace `<php-version>` variable with the PHP version that is used in your project.\
To get PHP version open [CLI](https://docs.create-magento-app.com/v1/getting-started/available-commands/cli) and execute `php --version` command.

{% hint style="info" %}
If you are using XDebug, set port 9111 in the configuration instead of 9003.

Port 9003 is the default for XDebug 3 and port 9111 is for XDebug 2.
{% endhint %}

### 3. Prepare browser

You need to install the [XDebug Helper](https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc) extension for Chrome to activate Debugging session in PHPStorm.&#x20;

Now when you open your CMA webpage you need to enable debug session by pressing **Debug** in the extensions menu.

{% hint style="warning" %}
VSCode debugger does not care what IDE key you select in xdebug helper settings.\
It automatically attaches when it sees a cookie with a name `XDEBUG_SESSION`.
{% endhint %}

{% hint style="info" %}
This extension sets a cookie in your browser's requests: `XDEBUG_SESSION=PHPSTORM`. This cookie enables debugging in your browser.

Sometimes, you may want to enable debugging outside of the browser (for example, to debug individual GraphQL requests). You can also set `XDEBUG_SESSION=PHPSTORM` manually in the `Cookie` header. Most HTTP and GraphQL clients support this option.
{% endhint %}

### 4. Start debugging

Open debugging tab in VSCode (**Ctrl + Shift + D)** and select **Listen for Xdebug** configuration.

![](https://3863794383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MOVnS5lKxiIvOL9no4d%2F-MlKvQf6F2140tXw0BX2%2F-MlKyJn6mBiUVuAdbliM%2FScreenshot_20211006_171926.png?alt=media\&token=e02671dc-bbe7-4216-ac91-38149c22a1b0)

Click on **Start debugging** (or press **F5)**, put test breakpoint in **$project\_root/pub/index.php** file, reload the page and that is all!

Happy debugging!