SDK PHP pur

Le package cœur : zéro dépendance, compatible PHP ≥ 7.4 (mutualisés, vieux projets et CMS inclus). C'est la fondation des ponts Laravel et Symfony, et l'outil du tracking « imblocable » sur n'importe quel site PHP.

Installation

composer require quiet-metrics/php-metrics

Utilisation

use QuietMetrics\Client;

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

$qm->pageview();                         // contexte déduit de la requête courante
$qm->event('achat', ['montant' => 49]);  // événement personnalisé

Le contexte (URL, referrer, IP, User-Agent, langue) est déduit des superglobales de la requête courante, et chaque champ est surchargeable :

$qm->pageview(['url' => 'https://monsite.fr/merci', 'referrer' => null]);

Options du constructeur

$qm = new Client('qm_pub_…', 'qm_sec_…', [
    'endpoint' => 'https://quietmetrics.dev/api/v1/collect', // défaut
    'timeout_ms' => 400,            // budget total d'envoi (min 50 ms)
    'async' => true,                // socket fire-and-forget ; false = cURL court
    'trust_proxy_headers' => false, // lire X-Forwarded-For / -Proto (reverse proxy)
    'defaults' => [],               // champs fusionnés dans chaque envoi
]);

defaults est pratique en multi-sites : instanciez un client par site avec sa clé, ou fixez une langue/URL de repli commune.

Mode signé (recommandé)

Avec la clé secrète, chaque envoi porte les en-têtes X-QM-Timestamp et X-QM-Signature (HMAC-SHA256 de "{timestamp}.{corps}"). Seule une signature valide autorise le service à prendre en compte l'IP et le navigateur du visiteur transmis dans le payload ; sans elle, c'est votre serveur qui serait compté comme unique visiteur.

Deux points d'attention :

• Horloge serveur. La signature est rejetée au-delà de ±5 minutes d'écart (anti-rejeu). Un serveur synchronisé NTP n'y pense jamais ; un conteneur à l'horloge figée, si.
• La clé secrète ne doit jamais apparaître côté navigateur ni dans un dépôt public.

Depuis le CLI, un cron, un worker

Hors requête HTTP, il n'y a ni URL ni IP courantes : sans url explicite, l'envoi est abandonné en silence. Passez le contexte :

$qm->event('facture-generee', ['montant' => 99], [
    'url' => 'https://monsite.fr/factures',
    'ts' => time(),
]);

Hébergement mutualisé

L'envoi tente d'abord une socket sortante (fsockopen, fire-and-forget, ~1 ms perçu). Si l'hébergeur la désactive, repli automatique sur cURL en requête courte. Si les deux sont indisponibles, l'envoi est abandonné en silence : votre site ne casse jamais.

Proxy first-party pour le script

Le fichier examples/qm-proxy.php relaie les envois du navigateur via votre domaine ; les listes de blocage par domaine ne voient que votre site :

1. Déposez qm-proxy.php et une copie de qm.js à la racine du site.
2. Renseignez les constantes QM_ENDPOINT et QM_SECRET dans l'en-tête du fichier (avec la clé secrète, l'IP et le navigateur du visiteur sont pris en compte).
3. Pointez le script dessus :

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

Côté CSP, script-src 'self' et connect-src 'self' suffisent : plus aucun domaine tiers côté navigateur.

Pages servies depuis un cache

Une page servie depuis un cache placé devant votre application n'exécute pas PHP : sa visite n'est pas comptée. Laissez ces pages hors du cache, ou ajoutez aussi le script qm.js : les deux mesures cohabitent sans double compte.

Ce qui est transmis

À partir de la version 0.5.0, seul ce que Quiet Metrics lit quitte votre serveur. L'adresse de la page part réduite à son origine et à son chemin, avec les seuls paramètres de campagne utm_source, utm_medium, utm_campaign et ref : les champs d'un formulaire envoyé en GET, un jeton ou une adresse e-mail dans l'URL restent chez vous. Le référent part réduit à son origine (https://www.google.fr/). La règle s'applique aussi à une adresse passée en surcharge ('url' => …), et une adresse sans hôte n'est pas envoyée.

Limites du payload

Payload JSON ≤ 4 Ko, nom d'événement ≤ 120 caractères, ≤ 30 propriétés scalaires (valeurs tronquées à 190 caractères). Au-delà, l'envoi est abandonné ou tronqué côté service, sans jamais d'erreur visible.

Contrat de robustesse

Ne casse jamais le site hôte : envoi non bloquant, replis automatiques, et tout échec (réseau, DNS, plateforme indisponible) est silencieux par contrat.