SDK PHP puro

El paquete núcleo: cero dependencias, compatible con PHP ≥ 7.4 (hosting compartido, proyectos antiguos y CMS incluidos). Es la base de los puentes de Laravel y Symfony, y la herramienta del seguimiento «imbloqueable» en cualquier sitio PHP.

Instalación

composer require quiet-metrics/php-metrics

Uso

use QuietMetrics\Client;

$qm = new Client('qm_pub_XXXXXXXXXXXXXXXXX', 'qm_sec_XXXXXXXXXXXXXXXX');

$qm->pageview();                          // contexto deducido de la petición actual
$qm->event('compra', ['importe' => 49]);  // evento personalizado

El contexto (URL, referrer, IP, User-Agent, idioma) se deduce de las superglobales de la petición actual, y cada campo puede sobrescribirse:

$qm->pageview(['url' => 'https://misitio.es/gracias', 'referrer' => null]);

Opciones del constructor

$qm = new Client('qm_pub_…', 'qm_sec_…', [
    'endpoint' => 'https://quietmetrics.dev/api/v1/collect', // predeterminado
    'timeout_ms' => 400,            // presupuesto total de envío (mín. 50 ms)
    'async' => true,                // socket fire-and-forget; false = cURL corto
    'trust_proxy_headers' => false, // leer X-Forwarded-For / -Proto (reverse proxy)
    'defaults' => [],               // campos fusionados en cada hit
]);

defaults resulta práctico en configuraciones multi-sitio: instancie un cliente por sitio con su clave, o fije un idioma/URL de respaldo comunes.

Modo firmado (recomendado)

Con la clave secreta, cada envío lleva las cabeceras X-QM-Timestamp y X-QM-Signature (HMAC-SHA256 de "{timestamp}.{cuerpo}"). Solo una firma válida autoriza al servicio a tener en cuenta la IP y el navegador del visitante transmitidos en el payload; sin ella, sería su servidor el que se contaría como único visitante.

Dos puntos de atención:

• Reloj del servidor. La firma se rechaza más allá de ±5 minutos de desfase (anti-replay). Un servidor sincronizado por NTP nunca tiene que pensarlo; un contenedor con el reloj congelado, sí.
• La clave secreta no debe aparecer nunca en el lado del navegador ni en un repositorio público.

Desde la CLI, un cron, un worker

Fuera de una petición HTTP, no hay URL ni IP actuales: sin una url explícita, el envío se abandona en silencio. Pase el contexto:

$qm->event('factura-generada', ['importe' => 99], [
    'url' => 'https://misitio.es/facturas',
    'ts' => time(),
]);

Hosting compartido

El envío intenta primero un socket saliente (fsockopen, fire-and-forget, ~1 ms percibido). Si el proveedor de hosting lo desactiva, repliegue automático a cURL con una petición corta. Si ambos no están disponibles, el envío se abandona en silencio: su sitio nunca se rompe.

Proxy first-party para el script

El archivo examples/qm-proxy.php retransmite los hits del navegador a través de su dominio, de modo que las listas de bloqueo por dominio solo ven su sitio:

1. Coloque qm-proxy.php y una copia de qm.js en la raíz del sitio.
2. Rellene las constantes QM_ENDPOINT y QM_SECRET en la cabecera del archivo (con la clave secreta, la IP y el navegador del visitante se tienen en cuenta).
3. Apunte el script hacia él:

<script defer src="/qm.js" data-site="qm_pub_…" data-endpoint="/qm-proxy.php"></script>

En cuanto a la CSP, script-src 'self' y connect-src 'self' bastan: ya no queda ningún dominio de terceros en el lado del navegador.

Límites del payload

Payload JSON ≤ 4 KB, nombre de evento ≤ 120 caracteres, ≤ 30 propiedades escalares (valores truncados a 190 caracteres). Más allá, el envío se abandona o se trunca en el lado del servicio; nunca hay un error visible.

Contrato de robustez

No rompe nunca el sitio anfitrión: envío no bloqueante, repliegues automáticos, y cualquier fallo (red, DNS, plataforma no disponible) es silencioso por contrato.