PHP SDK

Measure features

feature($key) returns a handle; the same key returns the same handle, so you can measure from several files. Keys are ^[a-z][a-z0-9_]{0,63}$. Anything the server contract would reject is dropped at collection time rather than sent.

$gallery = $insights->feature('gallery_block');

There are three kinds of measurement, and the difference matters for what the dashboard can say.

Flags and labels — a literal, given now:

$gallery->flag('enabled', true);
$gallery->value('layout', 'masonry');   // bool or string only; numbers are refused

Gauges — a callback, run once per snapshot, never on a page load. This is deliberate: only you know how to count your own things cheaply, and the SDK is forbidden from running your COUNT query on every request.

$gallery->gauge('instances', static function (): int {
    return (int) get_option('acme_gallery_count', 0);
});

Counters — additions and removals, batched into one option write at shutdown, so they cost an array write on your save path even inside a loop:

$gallery->added('instances');          // +1
$gallery->removed('instances', 3);

A counter pairs with a gauge of the same name: the snapshot carries instances, instances_added and instances_removed, and the dashboard reads the counter as movement between snapshots. value('instances', 9) followed by added('instances') is the mistake this guards against — the number would arrive and the counter would be silently lost — so value() refuses a number and tells you a gauge is what you meant.

Register measurements on every request — registration is free and nothing is resolved until the snapshot is built. A plugins_loaded or init callback is the usual place.

Limits, enforced client-side so no request is spent finding out: 256 features per snapshot, 64 measurements per feature, string values ≤ 128 characters.