SDK Laravel

Pageviews serveur automatiques (middleware), façade pour les événements : le tracking se fait à 100 % côté serveur, sans cookie de pistage ni JS, invisible pour les adblockers. Compatible Laravel 10 à 13, PHP ≥ 8.1.

Installation

composer require quiet-metrics/laravel-metrics

Le service provider et l'alias de façade sont enregistrés automatiquement (package discovery).

Mettre à jour

Chaque version mineure 0.x du pont exige la version mineure correspondante du SDK cœur quiet-metrics/php-metrics : montez les deux ensemble, et eux seuls.

composer require quiet-metrics/laravel-metrics:^0.5 --no-update
composer update quiet-metrics/laravel-metrics quiet-metrics/php-metrics

Un simple composer require échoue, car le SDK cœur est verrouillé dans composer.lock. Le message d'erreur de Composer propose alors -W : cette option met à jour toutes les dépendances du projet, Laravel compris. Lisez le CHANGELOG du paquet avant de monter : il signale les changements dans ce qui est compté.

Configuration

Les variables d'environnement suffisent dans la plupart des cas :

QUIET_METRICS_PUBLIC_KEY=qm_pub_XXXXXXXXXXXXXXXXX
QUIET_METRICS_SECRET_KEY=qm_sec_XXXXXXXXXXXXXXXX
# QUIET_METRICS_ENDPOINT=https://quietmetrics.dev/api/v1/collect

Fichier de configuration publiable si besoin (config/quiet-metrics.php) :

php artisan vendor:publish --tag=quiet-metrics-config

Pageviews automatiques

Le middleware quiet-metrics envoie la page vue dans terminate(), après l'envoi de la réponse : aucun impact sur la latence perçue. Par route ou par groupe :

Route::middleware('quiet-metrics')->group(function () {
    Route::get('/', HomeController::class);
    // …
});

Pour mesurer tout le trafic web d'un coup (Laravel 11+) :

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->appendToGroup('web', \QuietMetrics\Laravel\Middleware\TrackPageview::class);
})

Les pages vues automatiques sont les documents HTML/XHTML affichés en réponse à un GET, y compris les erreurs 404/500 levées par une route de votre application (abort(404), modèle introuvable). Les redirections, réponses vides (204/205), PDF, JSON et pièces jointes sont exclus, ainsi que l’AJAX, les préchargements annoncés et les visiteurs exclus.

Les adresses qui ne correspondent à aucune route ne sont pas mesurées par l'intégration dans le groupe web : quand aucune route ne correspond, Laravel n'exécute aucun middleware de groupe. Ces 404 comprennent les liens cassés et les anciennes adresses, mais aussi la plupart des requêtes de robots qui sondent les sites (/wp-login.php, /.env). Pour les mesurer quand même, déclarez le middleware dans la pile globale, à la place du groupe web :

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\QuietMetrics\Laravel\Middleware\TrackPageview::class);
})

La pile globale couvre aussi les routes hors du groupe web, comme un panneau d'administration : écartez-les avec les chemins exclus dans les réglages du site. Ne déclarez pas le middleware aux deux endroits, sinon chaque page serait comptée deux fois.

À partir de la version 0.4.0, 'track_404' => true active en plus un événement 404 avec le chemin de la page, sur les seules 404 que le middleware voit. Cette option est désactivée par défaut : chaque événement supplémentaire consomme le quota. Activez-la côté serveur ou via data-404 dans le script sur une même page, pour éviter un double événement. Le suivi ne voit pas les pages servies par un cache qui contourne PHP.

Événements

use QuietMetrics\Laravel\Facades\QuietMetrics;

QuietMetrics::event('inscription', ['plan' => 'pro']);

Depuis un job, une commande ou un listener (hors requête HTTP), il n'y a pas d'URL courante : passez-la explicitement, sinon rien ne part (abandon silencieux) :

QuietMetrics::event('import-termine', ['lignes' => 1200], [
    'url' => 'https://monsite.fr/imports',
]);

Cas particuliers

Cache pleine page (Varnish, Cloudflare, cache de réponses…). 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.

Octane, workers persistants. Le contexte (URL, referrer, IP, User-Agent, langue) vient de l'objet Request de chaque requête, jamais des superglobales. Rien à configurer.

Reverse proxy / CDN. Le middleware lit $request->ip() : configurez les trusted proxies de votre application Laravel comme d'habitude, et l'IP réelle du visiteur suivra. L'option trust_proxy_headers du SDK cœur ne sert que hors Laravel.

Environnements. Utilisez une clé de site distincte par environnement (.env de staging vs production), ou ne mettez simplement pas de clé en staging : sans clé publique, rien n'est envoyé.

Ce qui est transmis. À partir de la version 0.5.0, le SDK ne transmet que ce que Quiet Metrics lit : l'adresse de la page réduite à son origine, à son chemin et à ses paramètres de campagne, et le référent réduit à son origine. Détail dans le SDK PHP.

Tests. À partir de la version 0.5.0, QuietMetrics::fake() remplace le client par un faux qui enregistre au lieu d'envoyer. Les pages vues du middleware y passent aussi.

use QuietMetrics\Laravel\Facades\QuietMetrics;

QuietMetrics::fake();

$this->post('/register', [...])->assertRedirect();

QuietMetrics::assertEventSent('inscription', ['plan' => 'pro']);
QuietMetrics::assertPageviewSent();

Autres assertions : assertEventNotSent('nom') et assertNothingSent(). Le faux enregistre ce que votre application demande, avant la minimisation faite à l'envoi. Si votre code reçoit le client par injection, typez QuietMetrics\Tracker plutôt que QuietMetrics\Client : c'est ce qui le rend remplaçable. Pour qu'une suite sans faux n'envoie rien, videz la clé publique dans phpunit.xml (<env name="QUIET_METRICS_PUBLIC_KEY" value=""/>).

Contrat de robustesse

L'envoi est non bloquant (socket fire-and-forget, ~1 ms perçu, repli cURL court) et tout échec est silencieux : l'analytics ne casse jamais le site hôte, même si la plateforme est injoignable.