PHPackages                             aubes/correlation-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. aubes/correlation-bundle

ActiveSymfony-bundle[Logging & Monitoring](/categories/logging)

aubes/correlation-bundle
========================

Correlation ID propagation for Symfony: storage, generation, HTTP, and optional integrations for Monolog, Messenger, Mercure, and HTTP Client

v0.2.1(1mo ago)18MITPHPPHP ^8.2CI passing

Since Apr 11Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/aubes/correlation-bundle)[ Packagist](https://packagist.org/packages/aubes/correlation-bundle)[ Docs](https://github.com/aubes/correlation-bundle)[ RSS](/packages/aubes-correlation-bundle/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (18)Versions (4)Used By (0)

aubes/correlation-bundle
========================

[](#aubescorrelation-bundle)

[![CI](https://github.com/aubes/correlation-bundle/actions/workflows/php.yml/badge.svg)](https://github.com/aubes/correlation-bundle/actions/workflows/php.yml)[![Latest Stable Version](https://camo.githubusercontent.com/072af96edf478a93f416854451aad5f187948587b707720182c1cd1d5d365cb6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f61756265732f636f7272656c6174696f6e2d62756e646c65)](https://packagist.org/packages/aubes/correlation-bundle)[![PHP Version](https://camo.githubusercontent.com/6548c4ba93e80b7262d2dcb68f85dc51394a933970c92196d90e16024435c98b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f61756265732f636f7272656c6174696f6e2d62756e646c652f706870)](https://packagist.org/packages/aubes/correlation-bundle)[![License](https://camo.githubusercontent.com/d039e9e653a97be1dee123ad3c492e7e8b5acf0dffad1de04b03666c6e531ac3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f61756265732f636f7272656c6174696f6e2d62756e646c65)](https://packagist.org/packages/aubes/correlation-bundle)

Lightweight distributed tracing for Symfony. Propagates a correlation ID across your entire stack (HTTP, HTTP Client, Monolog, Messenger, Mercure, Twig) without the overhead of a full APM solution.

**Worker-mode ready**: the storage implements `ResetInterface` and is scoped per request/message. Works out of the box with FrankenPHP worker mode and Messenger workers.

Requirements
------------

[](#requirements)

- PHP >= 8.2
- Symfony 6.4 / 7.4 / 8.x

Installation
------------

[](#installation)

```
composer require aubes/correlation-bundle
```

The bundle auto-registers via Symfony Flex.

How it works
------------

[](#how-it-works)

The bundle captures or generates a correlation ID at the start of each HTTP request or console command, stores it in a request-scoped storage, and propagates it to all configured integrations.

### Core (always active)

[](#core-always-active)

- **Storage**: `CorrelationIdStorage` is `final`, self-materializes an ID via the configured generator on first `get()`, and memoizes the result
- **Contract**: `CorrelationIdProviderInterface::get()` always returns a valid, non-null string
- **Validation**: `set()` validates its input (printable ASCII, 1-255 chars) and throws `InvalidCorrelationIdException` on invalid values. Last write wins
- **Reset**: implements `ResetInterface` for worker/long-running process safety
- **Console**: correlation ID generated automatically per command, overridable via `--correlation-id`

### HTTP (always active)

[](#http-always-active)

- Captures `X-Correlation-Id` from incoming requests (configurable header name)
- Generates a new ID when the header is missing
- Echoes the ID in the response header

### Optional integrations

[](#optional-integrations)

Each integration activates automatically when its dependency is installed, and can be explicitly disabled.

IntegrationDependencyWhat it doesHTTP Client`symfony/http-client`Forwards the correlation ID as a header on outgoing HTTP requests. Any caller-provided correlation header is overwritten (the storage is the single source of truth)Monolog`monolog/monolog`Injects the ID into every log record's `extra` arrayMessenger`symfony/messenger`Stamps the ID on dispatch, restores it on consumeMercure`symfony/mercure-bundle`Injects the ID into JSON object payloadsTwig`twig/twig`Provides a `correlation_id()` template functionConfiguration
-------------

[](#configuration)

```
# config/packages/correlation.yaml
correlation:
    # Core
    generator: 'Aubes\CorrelationBundle\Generator\UuidCorrelationIdGenerator'  # or Hex32CorrelationIdGenerator
    uuid_version: 7  # 4, 6, or 7 (ignored when using a non-UUID generator)

    # HTTP
    http:
        header_name: 'X-Correlation-Id'
        send_response_header: true

    # Optional integrations
    http_client:
        enabled: true
        header: 'X-Correlation-Id'
        force_header: true  # false = caller-provided header takes precedence
        clients: ['http_client']

    monolog:
        enabled: true
        field_name: 'correlation_id'
        channels: []   # empty = all channels
        handlers: []   # empty = all handlers

    messenger:
        enabled: true
        buses: []      # empty = all buses

    mercure:
        enabled: true
        field_name: 'correlation_id'
        hubs: ['default']

    twig:
        enabled: true
```

All values shown above are defaults. Zero configuration is needed for the common case.

Interfaces
----------

[](#interfaces)

### `CorrelationIdProviderInterface`

[](#correlationidproviderinterface)

Read-only access. Inject this when you only need to read the current ID.

```
use Aubes\CorrelationBundle\Storage\CorrelationIdProviderInterface;

final class MyService
{
    public function __construct(private readonly CorrelationIdProviderInterface $provider) {}

    public function doSomething(): void
    {
        $correlationId = $this->provider->get(); // guaranteed non-null
    }
}
```

### `CorrelationIdStorageInterface`

[](#correlationidstorageinterface)

Full access: read, write, and reset. Extends `CorrelationIdProviderInterface` and `ResetInterface`.

```
public function get(): string;
public function set(string $id): void; // throws InvalidCorrelationIdException
public function reset(): void;
```

### `CorrelationIdGeneratorInterface`

[](#correlationidgeneratorinterface)

```
public function generate(): string;
```

Extension points
----------------

[](#extension-points)

### Built-in generators

[](#built-in-generators)

GeneratorFormatUse case`UuidCorrelationIdGenerator` (default)UUID v4/v6/v7 (`550e8400-e29b-…`)General-purpose correlation`Hex32CorrelationIdGenerator`32-char lowercase hex (`a1b2c3d4…`)W3C Trace Context / ECS `trace.id` compatibilityTo switch generator:

```
correlation:
    generator: 'Aubes\CorrelationBundle\Generator\Hex32CorrelationIdGenerator'
```

### Custom generator

[](#custom-generator)

Implement `CorrelationIdGeneratorInterface` and reference your service:

```
use Aubes\CorrelationBundle\Generator\CorrelationIdGeneratorInterface;

final class MyGenerator implements CorrelationIdGeneratorInterface
{
    public function generate(): string
    {
        // must return 1-255 printable ASCII characters
        return my_custom_id();
    }
}
```

```
correlation:
    generator: App\MyGenerator
```

> **Note**: the service referenced by `generator` must implement `Aubes\CorrelationBundle\Generator\CorrelationIdGeneratorInterface`.

### Seed the ID from a custom context

[](#seed-the-id-from-a-custom-context)

Inject `CorrelationIdStorageInterface` and call `$storage->set($id)` before the first downstream read:

```
use Aubes\CorrelationBundle\Exception\InvalidCorrelationIdException;

try {
    $storage->set($idFromExternalSource);
} catch (InvalidCorrelationIdException) {
    // untrusted source: fall back to the generator
}
```

Debug
-----

[](#debug)

The `correlation:debug` command displays active integrations, the generator class, and the current correlation ID:

```
php bin/console correlation:debug
```

When the Web Profiler is enabled, a correlation ID panel shows the ID source (generated vs provided) and the list of active integrations.

License
-------

[](#license)

MIT

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance89

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

3

Last Release

55d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3941035?v=4)[A. Bes](/maintainers/aubes)[@aubes](https://github.com/aubes)

---

Top Contributors

[![aubes](https://avatars.githubusercontent.com/u/3941035?v=4)](https://github.com/aubes "aubes (6 commits)")

---

Tags

bundlecorrelation-idsymfonysymfonybundletracingcorrelation-idobservabilitydistributed-tracing

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/aubes-correlation-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/aubes-correlation-bundle/health.svg)](https://phpackages.com/packages/aubes-correlation-bundle)
```

###  Alternatives

[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.4M195](/packages/sulu-sulu)[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k17.5M370](/packages/easycorp-easyadmin-bundle)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

84735.1k](/packages/flow-php-flow)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.4M506](/packages/shopware-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)