Extension configuration (INI)¶

All directives live in PHP's INI system. Scope decides where you can set it:

PERDIR — settable in .htaccess (php_value, mod_php), .user.ini (FPM / lsphp) and per-vhost ini files, in addition to php.ini.
SYSTEM — only meaningful in a global php.ini (or the ini include of the whole PHP binary). PERDIR directives can also be set in php.ini as the fleet-wide default.

Directives¶

Directive	Scope	Default	Meaning
`phpray.enabled`	PERDIR	`1`	Master switch. `0` = extension is inert (no tracing, no output).
`phpray.mode`	PERDIR	`smart`	`smart` = automatic level by request duration, `all` = full trace of every request, `manual` = only when triggered (console/CLI).
`phpray.smart_threshold_normal`	PERDIR	`200`	ms. Requests slower than this get a `normal` trace.
`phpray.smart_threshold_full`	PERDIR	`1000`	ms. Slower than this → `full` trace.
`phpray.smart_threshold_alert`	PERDIR	`3000`	ms. Slower than this → `alert` trace (never sampled).
`phpray.manual_sample_rate`	PERDIR	`10`	percent. In `manual` mode, share of requests traced when a trigger is active.
`phpray.always_trace_errors`	PERDIR	`1`	`1` = even fast requests that hit a PHP error get at least a `normal` trace.
`phpray.ignore_uris`	PERDIR	`""`	comma-separated URI prefixes (or ``) that are never traced, e.g. `/wp-cron.php,/assets/`.
`phpray.trace_cli`	SYSTEM	`0`	`1` = also trace CLI/SOAP/FPM workers, not just web SAPIs.
`phpray.emit_header`	PERDIR	`1`	Add the `X-PHPRay: <level>` response header so proxies/log collectors can see the level.
`phpray.capture_errors`	PERDIR	`1`	Capture PHP errors/warnings/notices into the trace record.
`phpray.output_mode`	SYSTEM	`file`	`file` = write JSONL to `output_path`, `shm` = write into shared memory for the collector, `both`.
`phpray.output_path`	SYSTEM	`/var/lib/phpray/traces`	Directory for JSONL trace files (when `file` or `both`).
`phpray.shm_path`	SYSTEM	`/dev/shm/phpray`	Base path of the shared-memory segment.
`phpray.shm_size`	SYSTEM	`64m`	Total shm size; the reader (collector) consumes ring-buffer records.
`phpray.profile_functions`	SYSTEM	`1`	`1` = register the function-call observer at startup (required for profiling; costs nothing unless profiling is on).
`phpray.profile_mode`	PERDIR	`sample`	`off` = no profiling, `sample` = random sample at `profile_sample_rate`, `url` = only URIs matching `profile_url`, `all` = every request.
`phpray.profile_sample_rate`	PERDIR	`3`	percent of requests that get a per-function profile.
`phpray.profile_url`	PERDIR	`""`	comma-separated URI prefixes to profile when `profile_mode=url`, e.g. `/checkout/,/cart/`.
`phpray.profile_max_components`	SYSTEM	`64`	cap on distinct components (plugins/functions) stored per trace.
`phpray.crash_threshold`	SYSTEM	`3`	alerts: N `alert`-level requests per window → crash alert to the collector.
`phpray.crash_window`	SYSTEM	`60`	seconds, window for the crash threshold.

Recipes¶

1. Disable for one site¶

In that site's ~/.user.ini (FPM/lsphp) or .htaccess (mod_php):

php_value phpray.enabled=0

Everything else on the server keeps tracing; this docroot is inert.

2. Profile one URL for a debugging session¶

Temporarily, for one site:

php_value phpray.profile_mode=url
php_value phpray.profile_url=/checkout/
php_value phpray.profile_sample_rate=100

Visit /checkout/ a few times, read the per-function breakdown in the dashboard (phpray trace <domain> / dashboard → site → traces), then remove the three lines. Alternatively do this from the cloud console without touching ini: the collector pushes a time-boxed profile control message (see Ingest protocol, GET /v1/control).

3. Run with zero profiling¶

Fleet-wide in php.ini:

phpray.profile_mode=off

You keep always-on summaries, normal/full/alert traces and N+1/error detection, but the function-level observer never samples a request — minimal overhead (see Overhead).