SDK Laravel

Páginas vistas automáticas del lado del servidor (middleware), una fachada para los eventos. El seguimiento se hace 100 % del lado del servidor, sin cookies de rastreo ni JS, invisible para los bloqueadores. Compatible con Laravel 10 a 13, PHP ≥ 8.1.

Instalación

composer require quiet-metrics/laravel-metrics

El service provider y el alias de fachada se registran automáticamente (package discovery).

Actualizar

Cada versión menor 0.x del puente exige la versión menor correspondiente del SDK base quiet-metrics/php-metrics: actualice ambos a la vez, y solo esos dos.

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

Un simple composer require falla, porque el SDK base está bloqueado en composer.lock. El mensaje de error de Composer propone entonces -W: esa opción actualiza todas las dependencias del proyecto, Laravel incluido. Lea el CHANGELOG del paquete antes de actualizar: señala los cambios en lo que se cuenta.

Configuración

Las variables de entorno bastan en la mayoría de los casos:

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

Archivo de configuración publicable si es necesario (config/quiet-metrics.php):

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

Páginas vistas automáticas

El middleware quiet-metrics envía la página vista en terminate(), después del envío de la respuesta: ningún impacto en la latencia percibida. Por ruta o por grupo:

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

Para medir todo el tráfico web de una vez (Laravel 11+):

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

Las páginas vistas automáticas son documentos HTML/XHTML mostrados como respuesta a un GET, incluidos los errores 404/500 generados por una ruta de su aplicación (abort(404), modelo no encontrado). Se excluyen las redirecciones, las respuestas vacías (204/205), los PDF, JSON y archivos adjuntos, además de AJAX, precargas anunciadas y visitantes excluidos.

Las direcciones que no corresponden a ninguna ruta no se miden con la integración en el grupo web: cuando ninguna ruta corresponde, Laravel no ejecuta ningún middleware de grupo. Estos 404 incluyen los enlaces rotos y las direcciones antiguas, pero también la mayoría de las peticiones de robots que sondean los sitios (/wp-login.php, /.env). Para medirlos de todos modos, declare el middleware en la pila global, en lugar del grupo web:

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

La pila global también cubre las rutas fuera del grupo web, como un panel de administración: apártelas con las rutas excluidas en los ajustes del sitio. No declare el middleware en ambos sitios, o cada página se contaría dos veces.

Desde la versión 0.4.0, 'track_404' => true también emite un evento 404 con la ruta de la página, solo en los 404 que ve el middleware. Está desactivado por defecto: cada evento adicional consume cuota. Actívelo en el servidor o mediante data-404 en el script de una misma página para evitar duplicados. El seguimiento no ve las páginas servidas por una caché que evita PHP.

Eventos

use QuietMetrics\Laravel\Facades\QuietMetrics;

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

Desde un job, un comando o un listener (fuera de una petición HTTP), no hay URL actual: pásela explícitamente; de lo contrario, no se envía nada (abandono silencioso):

QuietMetrics::event('importacion-terminada', ['filas' => 1200], [
    'url' => 'https://misitio.es/imports',
]);

Casos particulares

Caché de página completa (Varnish, Cloudflare, caché de respuestas…). Una página servida desde una caché situada delante de su aplicación no ejecuta PHP: su visita no se cuenta. Deje esas páginas fuera de la caché o añada también el script qm.js: ambas mediciones conviven sin contar dos veces.

Octane, workers persistentes. El contexto (URL, referrer, IP, User-Agent, idioma) proviene del objeto Request de cada petición, nunca de las superglobales. No hay nada que configurar.

Reverse proxy / CDN. El middleware lee $request->ip(): configure los trusted proxies de su aplicación Laravel como de costumbre, y la IP real del visitante llegará correctamente. La opción trust_proxy_headers del SDK base solo sirve fuera de Laravel.

Entornos. Utilice una clave de sitio distinta por entorno (.env de staging vs producción), o simplemente no ponga ninguna clave en staging: sin clave pública, no se envía nada.

Lo que se transmite. Desde la versión 0.5.0, el SDK solo transmite lo que Quiet Metrics lee: la dirección de la página reducida a su origen, su ruta y sus parámetros de campaña, y el referente reducido a su origen. Detalle en el SDK PHP.

Tests. Desde la versión 0.5.0, QuietMetrics::fake() sustituye el cliente por un falso que registra en lugar de enviar. Las páginas vistas del middleware también pasan por él.

use QuietMetrics\Laravel\Facades\QuietMetrics;

QuietMetrics::fake();

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

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

Otras aserciones: assertEventNotSent('nombre') y assertNothingSent(). El falso registra lo que su aplicación pide, antes de la minimización aplicada al enviar. Si su código recibe el cliente por inyección, tipe QuietMetrics\Tracker en lugar de QuietMetrics\Client: es lo que lo hace sustituible. Para que una suite sin el falso no envíe nada, vacíe la clave pública en phpunit.xml (<env name="QUIET_METRICS_PUBLIC_KEY" value=""/>).

Contrato de robustez

El envío es no bloqueante (socket fire-and-forget, ~1 ms percibido, respaldo cURL corto) y cualquier fallo es silencioso: la analítica nunca rompe el sitio anfitrión, incluso si la plataforma está inaccesible.