> For the complete documentation index, see [llms.txt](https://docs.create-magento-app.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.create-magento-app.com/v1/usage-guide/enabling-xdebug.md).

# Enabling XDebug

## Enabling XDebug in PHPStorm

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

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

{% hint style="danger" %}
Do not run the following command with the [-s option](/v1/getting-started/available-commands/start.md#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](/files/-MP5f6cd5Z_zGAro-Aer)

#### 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.

![](/files/-MdrNFD-buAvTf1jH5LE)

#### 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](/v1/getting-started/available-commands/status.md) command.
{% endhint %}

![](/files/-MgkRrqXEzZJSGAmWv0a)

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.

![](/files/-MgkSRETZn2nr2YB9NfB)

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.

![](/files/-MP9paYlLVvTnpiCg1TC)

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](/v1/getting-started/available-commands/start.md) command with [debug](/v1/getting-started/available-commands/start.md#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](/v1/getting-started/available-commands/cli.md) 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.

![](/files/-MlKyJn6mBiUVuAdbliM)

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!