Profiling Slow PHP Code with Xdebug

Xdebug profiling records function call cost so developers can locate slow paths in a PHP request or CLI workload.

What It Does

Use trigger mode and a private output directory. Profile a reproducible CLI task and find its cachegrind file.

Requirements and Compatibility

Use a supported PHP runtime and install any third-party tool or extension explicitly shown in the examples. Commands should be run from the project root unless stated otherwise.

Syntax, Inputs and Results

The examples separate configuration, the smallest working operation and a realistic follow-up task. Adapt file paths and dependency versions to your own project.

Example 1: Basic Use

Use trigger mode and a private output directory.

zend_extension=xdebug
xdebug.mode=profile
xdebug.start_with_request=trigger
xdebug.output_dir=/tmp

Example 2: Another Case

Profile a reproducible CLI task and find its cachegrind file.

XDEBUG_MODE=profile XDEBUG_TRIGGER=1 php bin/report.php
ls -lh /tmp/cachegrind.out.*
XDEBUG_MODE=profile php bin/worker.php

Practical Example

Contrast profiler data with a local timing baseline.

<?php
$start = hrtime(true);
$numbers = range(1, 10000);
echo array_sum($numbers), ' in ', round((hrtime(true) - $start) / 1e6, 2), ' ms';

For production, apply the compatibility and edge-case limits described below.

Important Behavior and Edge Cases

Enable profiling only for selected workloads; output files can be large and reveal internal paths.

Comparison with Related Functions and Tools

Subject	Key difference
Step debugging vs profiling	Step debugging pauses individual statements; profiling records aggregate runtime cost.

Common Beginner Mistakes

Mistake	Correct approach
Enabling the debugger for every production request	Use controlled triggers and disable development modes in production.
Skipping the prerequisite of this specific workflow	Install or configure the named tool and confirm the example can actually run.
Ignoring edge conditions	Enable profiling only for selected workloads; output files can be large and reveal internal paths.

Key Takeaways

Xdebug profiling records function call cost so developers can locate slow paths in a PHP request or CLI workload.
Enable profiling only for selected workloads; output files can be large and reveal internal paths.
Keep application configuration, source code and validation tests under version control.

Use these examples as a starting point, then validate the result with the actual PHP build, dependencies and inputs used by your application.