php-profiler

PHP Sampling Profiler using the Excimer extension, with automatic per-request collection and a built-in flamegraph dashboard.

---

Features

• Zero-code instrumentation – add one line to php.ini and every request is profiled automatically.
• Flamegraph dashboard – interactive SVG flamegraph with zoom, tooltips, and frame highlighting.
• Endpoint ranking – requests grouped by URI path, sorted by total sample count.
• Merged view – all requests for the same endpoint are merged into a single flamegraph.
• Export JSON – download the merged folded-stacks profile for offline analysis.
• Automatic cleanup – keeps the newest 10 000 profiles; older files are pruned on each request.

---

Requirements

Requirement	Version
PHP	≥ 8.3
ext-excimer	any

---

Installation

composer require phpdevsr/php-profiler

Or clone / install directly to /opt/php-profiler:

git clone https://github.com/PHPDevsr/php-profiler /opt/php-profiler

---

Quick-start

1 – Enable auto-profiling in php.ini

auto_prepend_file = /opt/php-profiler/profiler.php

Optionally override the data directory:

; defaults to /opt/php-profiler/dataauto_prepend_file = /opt/php-profiler/profiler.php

Or via an environment variable:

PHP_PROFILER_DATA_DIR=/var/lib/php-profiler/data

2 – Expose the dashboard (Nginx example)

# Serve the dashboard at /profiler/location /profiler/ {alias /opt/php-profiler/dashboard/; # Restrict to localhost onlyallow127.0.0.1;deny all;indexindex.php;try_files$uri$uri/ /profiler/index.php?$query_string;location~\.php$ {fastcgi_pass unix:/run/php/php8.3-fpm.sock;fastcgi_indexindex.php;include fastcgi_params;fastcgi_param SCRIPT_FILENAME $request_filename;}}

Apache example:

Alias/profiler/opt/php-profiler/dashboard
<Directory/opt/php-profiler/dashboard>
Options -Indexes
AllowOverride None
Require ip 127.0.0.1DirectoryIndex index.php
</Directory>

3 – Open the dashboard

http://127.0.0.1/profiler/

Make a few HTTP requests to your application, then refresh the dashboard to see endpoint rankings and flamegraphs.

---

Library API

You can also use the Profiler class directly in your code:

usePHPDevsr\Profiler\Profiler;
$profiler = newProfiler(period: 0.01); // 10 ms sampling interval$profiler->start();
// … code to profile …$profiler->stop();
// Raw folded-stacks string (Excimer format, compatible with flamegraph tools)$folded = $profiler->getFoldedStacks();
// Parsed log: array of ['stack' => string[], 'count' => int]$log = $profiler->getLog();

FileStorage

usePHPDevsr\Profiler\Storage\FileStorage;
$storage = newFileStorage('/var/lib/php-profiler/data');
$storage->save([
'id' => uniqid('', true),
'timestamp' => microtime(true),
'endpoint' => '/api/users',
'method' => 'GET',
'duration_ms' => 45.2,
'sample_count' => 12,
'folded_stacks' => $profiler->getFoldedStacks(),
]);
// Endpoint statistics (sorted by total samples, descending)$stats = $storage->getEndpointStats();
// Profiles for one endpoint$profiles = $storage->findByEndpoint('/api/users');
// Delete oldest files when total exceeds $maxFiles$storage->cleanup(maxFiles: 10_000);

---

Development

# Run tests
composer test# Static analysis
composer phpstan
# Rector dry-run
composer rector

---

License

MIT — see LICENSE.