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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.create-magento-app.com/v1/usage-guide/enabling-xdebug.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.