Bundle de Symfony

Páginas vistas automáticas del lado del servidor vía kernel.terminate y configuración semántica. Compatible con Symfony 6.4 y 7, PHP ≥ 8.1.

Instalación

composer require quiet-metrics/symfony-metrics

Sin Symfony Flex, registre el bundle:

// config/bundles.php
return [
    // …
    QuietMetrics\Symfony\QuietMetricsBundle::class => ['all' => true],
];

Actualizar

Cada versión menor 0.x del bundle 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/symfony-metrics:^0.5 --no-update
composer update quiet-metrics/symfony-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, que actualiza todas las dependencias del proyecto; -w también actualizaría componentes de Symfony. Lea el CHANGELOG del paquete antes de actualizar: señala los cambios en lo que se cuenta.

Configuración

# config/packages/quiet_metrics.yaml
quiet_metrics:
    public_key: '%env(QUIET_METRICS_PUBLIC_KEY)%'   # clave pública del sitio (obligatoria)
    secret_key: '%env(QUIET_METRICS_SECRET_KEY)%'   # imprescindible en el envío desde el servidor: firma cada envío (HMAC)

    # endpoint: 'https://quietmetrics.dev/api/v1/collect'  # valor por defecto del SDK núcleo
    # auto_pageview: false        # desactiva la página vista automática

Por entorno, sobrescriba en config/packages/test/quiet_metrics.yaml o mediante las variables de entorno; sin una clave pública válida, no se envía nada.

Páginas vistas automáticas

Las páginas vistas automáticas son documentos HTML/XHTML mostrados como respuesta a un GET, incluidos los errores 404/500. 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.

Desde la versión 0.4.0, track_404: true también emite un evento 404 con la ruta de la página. 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.

auto_pageview: false desactiva el listener: usted conserva el cliente para envíos manuales (sitios mixtos, seguimiento selectivo).

Eventos

Inyecte QuietMetrics\Tracker, la interfaz que implementa el cliente (servicio público; QuietMetrics\Client antes de la versión 0.5.0):

use QuietMetrics\Tracker;

final class CheckoutController
{
    public function __construct(private readonly Tracker $quietMetrics) {}

    public function confirm(): Response
    {
        // …
        $this->quietMetrics->event('compra', ['importe' => 49, 'plan' => 'pro']);
    }
}

Desde un comando de consola o un worker de Messenger, no existe una petición en curso: pase la URL explícitamente, de lo contrario no se envía nada (descarte silencioso):

$this->quietMetrics->event('importacion-completada', ['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.

FrankenPHP, RoadRunner, workers persistentes. El listener lee el objeto Request de cada petición, nunca las superglobales. Nada que configurar.

Reverse proxy / CDN. El listener utiliza Request::getClientIp(): configure framework.trusted_proxies como de costumbre y la IP real del visitante seguirá. La opción trust_proxy_headers del SDK solo concierne a los usos fuera del framework.

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. Sustituya el servicio QuietMetrics\Tracker por su propia implementación para verificar sus eventos sin red. El cliente es final: no se extiende, se sustituye la interfaz que implementa (versión 0.5.0 y siguientes).

# config/services_test.yaml
services:
    QuietMetrics\Tracker:
        class: App\Tests\Double\RecordingTracker

Su código debe entonces tipar QuietMetrics\Tracker, como en el ejemplo de los eventos.

Contrato de robustez

Envío no bloqueante (socket fire-and-forget, respaldo cURL corto), fallos silenciosos: la analítica nunca rompe la aplicación anfitriona, incluso si la plataforma está inaccesible.