Download the PHP package dennisvanbeersel/symfony-logger-client without Composer

AppLogger Symfony Client

Symfony bundle for the AppLogger error tracking and application monitoring platform — automatic exception capture, log aggregation, a frontend JavaScript SDK, and non-blocking, resilient delivery.

What is this?

This package is the Symfony client bundle for AppLogger (applogger.eu), an EU-hosted, privacy-first error tracking and application/log monitoring SaaS built for Symfony and PHP applications.

Once installed and enabled, the bundle wires itself into your application and ships telemetry to the AppLogger platform through three channels:

• Error tracking — uncaught exceptions and exception-bearing Monolog records are sent to the platform, where they are grouped and fingerprinted into error groups (backed by PostgreSQL).
• Log aggregation — non-exception Monolog records at or above your configured capture level are batched and forwarded to the AppLogger log collector (backed by ClickHouse).
• Frontend errors — a bundled JavaScript SDK captures browser exceptions, unhandled promise rejections, and failed requests, with optional error-triggered session replay.

A central design goal of the bundle is that telemetry delivery never delays or breaks the host application. Sending is asynchronous and fire-and-forget by default, completes after the HTTP response has already been flushed to the user, and is guarded end-to-end so that no transport, encoding, or configuration failure propagates into your application's request handling.

The platform provides EU data residency, IP anonymization, PII scrubbing, and session-id hashing to support GDPR-conscious deployments.

Features

• Automatic exception capture — uncaught exceptions are captured via an event subscriber (no manual instrumentation required).
• Automatic Monolog capture — any Monolog record carrying a \Throwable in its context is routed to error tracking; other records at or above your capture level are routed to log aggregation. Wiring is done automatically — you do not edit monolog.yaml.
• Non-blocking, resilient delivery — asynchronous transport with a per-pipeline circuit breaker; delivery is completed on kernel.terminate (after the response is sent), with a bounded fallback for CLI and Messenger workers.
• Never throws into the host — the dispatch path is wrapped so transport, encoding, and configuration failures are recorded internally rather than surfaced to your code.
• Log aggregation — buffered, batched log shipping to the AppLogger log collector with memory-bounded buffers.
• Bundled JavaScript SDK — frontend error capture with its own client-side circuit breaker, offline queue, rate limiting, and deduplication. Optional automatic injection via Twig.
• Error-triggered session replay (opt-in) — captures DOM snapshots and interactions around an error; sent together with the error payload.
• GDPR-oriented data scrubbing — key-based redaction of sensitive fields, query-string and URL credential redaction, and IP anonymization, all performed before data leaves your host.
• Inert-by-default install — auto-registers via Symfony Flex and ships disabled until you opt in; installs cleanly even in API-only apps without Twig.

Requirements

The Composer-enforced runtime requirements are:

Note: The JavaScript SDK is shipped pre-built in assets/dist/, so a Node.js toolchain is not required to use it. symfony/asset-mapper, symfony/twig-bundle, and twig/twig are development dependencies of this package — their absence in your application is tolerated, and the bundle remains fully functional. AssetMapper integration is wired automatically when AssetMapper is present; the Twig-based JS auto-injection is simply removed when Twig is not installed.

Installation

Install with Composer:

With Symfony Flex (recommended)

If your application uses Symfony Flex, the bundle is registered automatically and a Flex recipe is applied. The recipe:

• registers ApplicationLogger\Bundle\ApplicationLoggerBundle for all environments,
• installs a config/packages/application_logger.yaml configuration file,
• appends environment-variable placeholders to your .env:

The bundle ships inert after installation. Both PHP error tracking and the JavaScript SDK are gated on APPLICATION_LOGGER_ENABLED, which the recipe sets to false. To start sending telemetry, set your real credentials (preferably in .env.local) and flip the flag:

Two credentials, two purposes. The api_key (format: any string) is your server-side secret — it is sent from PHP via X-Api-Key and must never appear in browser-facing HTML. The publishable_key (format: pk_live_…) is a write-only, browser-safe key — it is embedded in the auto-injected JS SDK and used exclusively for browser JS error ingest at /api/v1/js-errors via X-Publishable-Key. Obtain the publishable key from your project's Settings > Publishable Keys page on AppLogger.

The recipe also defaults release to %env(default::APP_VERSION)%, environment to %kernel.environment%, and debug to %kernel.debug%.

Without Flex (manual setup)

1. Register the bundle in config/bundles.php:

2. Create config/packages/application_logger.yaml. A minimal configuration needs a DSN, a server-side API key, and — to enable browser JS error tracking — a publishable key:

3. Add the corresponding environment variables to .env / .env.local and clear the cache:

The bundle does not require a Monolog handler to be declared by hand. It prepends its own service-type Monolog handler automatically on the channels !event, !request, and !php (those framework channels are excluded to avoid double-recording uncaught exceptions, which are already handled by the exception subscriber).

Configuration

The configuration root key is application_logger. The DSN and API key are the only values required to start sending; everything else has a sensible default.

v2.0 note: The bundle is now a thin Symfony adapter over applogger/sdk-core. Error capture routes through the SDK Hub; log aggregation routes through LogClient. Several configuration keys that were previously active (endpoint_path, log_path, log_batch_size, max_log_buffer, retry_attempts, async, circuit_breaker.enabled) are now deprecated no-ops — they are accepted without error but have no effect, and will be removed in a future major version. Remove them from your config to silence deprecation notices.

DSN and authentication

The DSN identifies your project endpoint and has the form:

The client-internal parser validates that a project-id path segment exists. The API key is not embedded in the DSN — it is sent separately in the X-Api-Key request header.

Authentication summary:

Inertness rules:

• An empty DSN or API key makes the corresponding feature short-circuit silently (no requests, no errors).
• A non-empty but malformed DSN is treated as active misconfiguration and raises InvalidArgumentException (so genuine misconfiguration surfaces early rather than silently dropping telemetry).
• If log_endpoint or log_token is empty/null, log aggregation silently no-ops.

Core options

Log aggregation

Performance & resilience

Circuit breaker (circuit_breaker)

The circuit breaker is owned by applogger/sdk-core in v2.0 and is always-on. The enabled key is accepted but has no effect.

Capture

JavaScript (javascript)

Session tracking (session_tracking)

Session replay (session_replay)

These values are forwarded to the JavaScript SDK. Replay is error-triggered only (never continuous). See Session replay for the important note on default state.

Realistic example

Usage

Automatic exception capture (zero-config)

Once the bundle is enabled with a valid DSN and API key, uncaught exceptions are captured automatically. The exception subscriber listens on kernel.exception at a low priority (-100, after the framework's own handlers), extracts the HTTP status code (the status of an HttpExceptionInterface, otherwise 500), attaches exception_class and exception_code tags plus a breadcrumb, and sends the error payload. The subscriber is wrapped in its own try/catch and never interferes with your application's exception handling.

No code changes are needed for this.

Manual capture via Monolog

Because the bundle auto-registers a Monolog handler, the most natural way to record events from your own code is to log through Monolog. The handler routes records by content:

• a record whose context['exception'] is a \Throwable is sent to error tracking;
• any other record at or above capture_level is sent to log aggregation.

Log aggregation via Monolog

Records without an exception that meet the capture_level threshold are buffered and shipped to the log collector in batches:

Each record is converted into a log entry with an RFC3339 timestamp, an RFC5424 severity keyword (debug, info, notice, warning, error, critical, alert, emergency), the Monolog channel as the application name, the environment, and a scrubbed, flattened context map. Entries are sent to POST <log_endpoint><log_path> (or the /batch variant for batches); a successful ingestion returns HTTP 202 Accepted. If no log_endpoint / log_token is configured, log aggregation is silently skipped.

Smoke-test the log channel

Verify collector credentials without booting Symfony:

Or, with the bundle installed: php bin/console application-logger:test.

LogEntry fields: timestamp (RFC3339), severity (syslog keyword), message (≤8000), app_name (≤255), environment, context (map of string→string).

JavaScript SDK

The bundled SDK uses the publishable key (pk_live_…) for browser error ingest — never the secret api_key. The publishable key is write-only and safe to embed in HTML. Obtain it from your project's Settings > Publishable Keys page on AppLogger, then set it in .env.local:

and declare it in config/packages/application_logger.yaml:

When publishable_key is non-empty and javascript.enabled is true (the default), the bundle auto-injects the SDK into eligible HTML responses. The SDK sends browser errors to /api/v1/js-errors via X-Publishable-Key.

With javascript.auto_inject enabled (the default), injection is automatic for main requests with a text/html content type, a status below 400, a </body> tag, and a body under 1 MiB. Error pages (4xx/5xx) are deliberately skipped.

If you prefer to place the SDK yourself (and Twig is available), disable auto_inject and call the Twig function just before </body>:

At runtime the SDK is exposed as window.appLogger. It automatically captures window error events, unhandled promise rejections, failed fetch/HTTP requests, and console.error() breadcrumbs. When expose_api is enabled (the default), you can also report manually:

The SDK is resilient on the client side too: a sessionStorage-backed circuit breaker (default threshold 5, 60s open window), a localStorage offline queue (default 50 events, 24h max age), token-bucket rate limiting (default burst of 10, refilling at ~10/minute — 0.167 tokens/second), and deduplication (default 5s window). On page close it uses the Beacon API to flush queued events. Breadcrumbs are capped at 50 by default.

Session replay (opt-in)

Session replay is error-triggered only — it never records continuously. When enabled, the SDK buffers a window of DOM snapshots and interactions before and after an error and sends that data together with the error payload (not as a separate request). Cross-page continuity is maintained via localStorage.

Session tracking (session_tracking.enabled) must be on for replay to function.

Important — default state: Replay is an opt-in feature. The JavaScript SDK itself defaults sessionReplayEnabled to false, while the bundle's PHP session_replay.enabled config node defaults to true; the effective value forwarded to the SDK is whatever the PHP configuration / Twig integration provides. Treat replay as opt-in and error-triggered, and explicitly confirm session_replay.enabled in your configuration to match your intended behavior. When expose_api is true, replay can also be toggled at runtime:

The non-blocking, never-throws guarantee

By default (async: true) telemetry is dispatched fire-and-forget and completed after the HTTP response has been flushed to the client:

• On the web, a kernel.terminate subscriber (priority -1024, runs last) flushes buffered logs and then completes any in-flight error requests, so the user is never delayed by telemetry. This also makes same-host self-monitoring safe — the send finishes after the response is sent.
• For CLI commands and Messenger workers (which have no kernel.terminate), a bounded destructor-based fallback completes outstanding requests within a short time budget.
• Post-response completion is capped (at min(timeout, 2.0) seconds) so a slow backend cannot stall worker recycling.

The single dispatch envelope is guarded throughout: the global kill-switch, JSON encoding, the circuit breaker, and the transport itself are all wrapped so failures are recorded internally and never thrown into your application. The only intentional exceptions are at construction time (an out-of-range timeout, or a non-empty but malformed DSN), which surface genuine misconfiguration early.

Privacy & GDPR

The bundle is designed to scrub sensitive data on your host, before anything is transmitted:

• Key-based field redaction. Values whose key name (case-insensitive substring match) contains a configured scrub fragment are replaced with [REDACTED], recursively (depth-limited). The default PHP scrub fields are:

  This redaction is key-based: values stored under non-matching keys are not inspected, so secrets embedded in free-form text under an innocuous key are not caught. Add your own field names via scrub_fields as needed. The JavaScript SDK maintains its own (broader) default scrub list — the two lists are kept in parallel rather than shared, so configure both if you add custom fields.

• URL and query-string redaction. Query-string values whose name matches a scrub fragment are redacted, and embedded userinfo credentials (user:pass@host) are always redacted, while scheme, host, port, path, and fragment are preserved.

• IP anonymization. IPv4 addresses have their last octet masked (e.g. 192.168.1.100 → 192.168.1.0); IPv6 addresses keep the first 48 bits and zero the remaining 80 bits. Invalid or null inputs return null — a raw IP is never echoed.

• Session-id hashing. Session identifiers are SHA-256 hashed before leaving the host.

The AppLogger platform itself is EU-hosted with EU data residency. As with any monitoring tool, review what your application logs and adjust scrub_fields to match your data-protection obligations.

The AppLogger.eu platform

AppLogger is an EU-hosted, privacy-first error tracking and application/log monitoring SaaS built on a Symfony stack:

• Error tracking — errors are grouped and fingerprinted into error groups, backed by PostgreSQL.
• Log aggregation — high-volume logs are stored in ClickHouse, ingested through a dedicated log collector.
• Privacy by design — EU data residency, IP anonymization, PII scrubbing, and session-id hashing.

Getting a DSN and tokens

1. Sign up at applogger.eu.
2. Create a project to obtain its DSN and API key (server-side; used for error and session tracking from PHP).
3. For browser JS error tracking, obtain the project's Publishable Key (pk_live_…) from Settings > Publishable Keys. This is safe to embed in HTML.
4. For log aggregation, obtain the project's log endpoint and log token (sk_log_…).
5. Put these values in your .env.local and set APPLICATION_LOGGER_ENABLED=true.

Links

• Website & sign-up: https://applogger.eu
• Package repository & issues: https://github.com/dennisvanbeersel/symfony-logger-client
• Documentation & guides (API, setup, security): https://applogger.eu

Contributing

Contributions are welcome. Please open issues and pull requests on the package repository.

The project follows PSR-12 with declare(strict_types=1) and is checked at PHPStan level 6. Convenience Composer scripts are provided:

Please ensure composer lint and composer test pass before submitting a pull request.

Security

If you discover a security vulnerability, please report it responsibly rather than opening a public issue. Use the security advisory channel on the package repository so it can be addressed before public disclosure.

License

Released under the MIT License.

Authored by Dennis Van Beersel — applogger.eu.