Profiling with Xdebug

Besides interactive debugging, PhpStorm integration with Xdebug also supports profiling. PhpStorm provides visual representation of profiling data generated by Xdebug. You can select several snapshots at a time and collect the aggregated profiling information.

Before profiling with Xdebug, download, install and configure the components of the PHP development environment. Normally, these are a PHP engine, a web server, and the Xdebug tool.

Enable profiling with Xdebug

Configure Xdebug

Enable the Xdebug profiler

Open the active php.ini file in the editor:
1. In the Settings/Preferences dialog (Ctrl+Alt+S), click PHP.
2. On the PHP page that opens, click next to the CLI Interpreter field.
3. In the CLI Interpreters dialog that opens, the Configuration file read-only field shows the path to the active php.ini file. Click Open in Editor.
Do one of the following:
- To permanently enable the profiler, set the xdebug.profiler_enable (for Xdebug 2) or xdebug.mode (for Xdebug 3) directive:
  xdebug.mode = profile;
  xdebug.profiler_enable = 1;
- To enable triggering the profiler from the browser by using the XDEBUG_PROFILE cookie or a GET/POST parameter, set the following directives depending on the Xdebug version used:
  xdebug.mode = profile; xdebug.start_with_request = trigger;
  xdebug.profiler_enable = 0; xdebug.profiler_enable_trigger = 1;

Configure the way to toggle the profiler from the browser

To specify the XDEBUG_PROFILE cookie or a GET/POST parameter, do one of the following:

Specify the values manually.
Generate the bookmarklets to toggle the debugger through. These bookmarklets will appear on the toolbar of your browser. They provide control over the debugger cookie, through them you will activate and deactivate the debugger.
1. Enable the Bookmarks toolbar in your browser by doing one of the following depending on the browser type:
  - In Firefox, choose View | Toolbar | Bookmarks Toolbar.
  - In Chrome, choose Bookmarks | Show bookmarks bar.
2. In the Settings/Preferences dialog (Ctrl+Alt+S), navigate to PHP | Debug.
3. On the Debug page, that opens, click the Use debugger bookmarklets to initiate debugger from your favorite browser link.
4. On the Zend Debugger & Xdebug bookmarklets page that opens, check the debugging engine settings and click Generate. The bookmarks for listed debugging-related actions are generated.
5. Drag the generated links to the bookmark toolbar in your browser.

Specify the location for storing accumulated profiling data

Open the active php.ini file in the editor:
1. In the Settings/Preferences dialog (Ctrl+Alt+S), click PHP.
2. On the PHP page that opens, click next to the CLI Interpreter field.
3. In the CLI Interpreters dialog that opens, the Configuration file read-only field shows the path to the active php.ini file. Click Open in Editor.
Define location for accumulating profiling snapshots by specifying the xdebug.profiler_output_dir (for Xdebug 2) or xdebug.output_dir (for Xdebug 3) directive.
xdebug.output_dir = "<path to output folder>"
xdebug.profiler_output_dir = "<path to output folder>"
Specify the name of the file to store snapshots in through the value of the xdebug.profiler_output_name directive. The default name is cachegrind.out.%p, where %p is the name format specifier. Accept the default name or define a custom one in compliance with the following standard:
1. The name should always be cachegrind.out.
2. Use the supported format specifiers.

Analyze Xdebug profiling data

When integration with Xdebug profiler is enabled, PhpStorm provides visual representation of profiler snapshots. PhpStorm opens a separate editor tab with four views where the data are presented based on different criteria.

Initiate an Xdebug debugging session

Do one of the following:

To start debugging an entire application, create debug configuration of the type PHP Web Page, and launch debugging by clicking .
See Debug with a PHP web page debug configuration for details.
To debug a specific PHP HTTP request, define a debug configuration of the type PHP HTTP Request, and launch debugging by clicking .
See Debug a PHP HTTP request for details.
To initiate a zero-configuration debugging session:
1. Toggle the Start Listen PHP Debug Connections button on the PhpStorm toolbar so that it changes to . After that PhpStorm starts listening to the port of the debugging engine used in the current project. Debugging ports are set at the PhpStorm level on the PHP | Debug page of the Settings/Preferences dialog (Ctrl+Alt+S).
2. Open the starting page of your application in the browser, choose the Start debugger bookmark to activate the debugging engine from the browser, re-load the current page (the starting page of the application), and then return to PhpStorm.

Retrieve the data accumulated by the profiler

From the main menu, choose Tools | Analyze Xdebug Profiler Snapshot….
In the Select Xdebug profiler snapshot dialog, that opens, choose the folder and the file where the profiling data is stored.
PhpStorm presents the collected profiling data in a separate editor tab with the name of the selected profiler output file.

Examine the profiling data

When you request on the accumulated profiling data, PhpStorm opens its visualized presentation in a separate editor tab. The tab is named after the selected profiler output file and consists of several views. Switch between the views to analyze the profiling data based on various criteria of analysis.

In the Execution Statistics view, examine the summary information about execution metrics of every called function.
In the Call Tree view, explore the execution paths of all called functions.
To explore the execution paths of a specific function, select the function in the Call Tree view and view its callees in the Callees view.
To explore all the paths that can result in calling a specific function, select the function in the Call Tree view and examine its possible callers in the Callers view.

Last modified: 19 March 2022