aubes/correlation-core

Core bundle for correlation ID management: storage, generator and shared contracts

v0.1.0 2026-04-06 12:42 UTC

Requires

• php: ^8.2
• symfony/config: ^6.4 | ^7.4 | ^8.0
• symfony/console: ^6.4 | ^7.4 | ^8.0
• symfony/dependency-injection: ^6.4 | ^7.4 | ^8.0
• symfony/http-kernel: ^6.4 | ^7.4 | ^8.0
• symfony/service-contracts: ^3.0
• symfony/uid: ^6.4 | ^7.4 | ^8.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.1
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^11.0 | ^12.0

MIT

• Aurélian Bes

• symfony
• bundle
• correlation-id
• tracing
• observability

README

Core bundle for correlation ID management: storage, generator, and shared interfaces.

Requirements

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

Interfaces

CorrelationIdProviderInterface

Read-only access to the current correlation ID. Inject this in your services when you only need to read the ID.

use Aubes\CorrelationCore\Storage\CorrelationIdProviderInterface;

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

    public function doSomething(): void
    {
        $correlationId = $this->provider->get(); // returns ?string
    }
}

CorrelationIdStorageInterface

Full access: read, write, and reset. Extends CorrelationIdProviderInterface and Symfony's ResetInterface.

public function get(): ?string;          // current ID, or null if not yet resolved
public function set(string $id): void;  // idempotent - no-op if an ID is already stored
public function getOrGenerate(): string; // returns current ID, or generates and stores one
public function reset(): void;          // clears the stored ID (called between contexts)

set() is intentionally idempotent: once a correlation ID is stored for a context, it cannot be overwritten. This prevents accidental ID changes mid-request.

CorrelationIdGeneratorInterface

public function generate(): string;

One implementation is provided:

Class	Output	Use case
UuidCorrelationIdGenerator	UUID v7 string	Default - human-readable, time-ordered

Custom generator

use Aubes\CorrelationCore\Generator\CorrelationIdGeneratorInterface;

class MyGenerator implements CorrelationIdGeneratorInterface
{
    public function generate(): string
    {
        return bin2hex(random_bytes(16));
    }
}

# config/packages/correlation_core.yaml
correlation_core:
    generator: App\MyGenerator

Console commands

A correlation ID is generated automatically at the start of every console command and cleared when it terminates. No configuration required.

--correlation-id option

Any command can receive a specific correlation ID via the global --correlation-id option:

php bin/console app:process-orders --correlation-id=01JQWXYZ...

If provided, the value is validated (printable ASCII, max 255 chars) before being stored. If omitted, a UUID v7 is generated.

Worker / long-running processes

CorrelationIdStorage implements Symfony's ResetInterface. The kernel calls reset() automatically between HTTP requests (FrankenPHP), ensuring the ID from one context never leaks into the next.

For console workers (Messenger consumers), the console listener resets the ID after each command terminates - the correlation ID from one job never leaks into the next.

License

MIT