ADR-0005: Named Multi-Client Configuration with Exactly-One-Default Invariant

Status

Accepted

Context

Applications sometimes need to query multiple Contentful spaces (e.g., a primary space + a preview space, or multiple brand spaces). The original bundle config (pre-4.0) had an inconsistent structure for single vs. multi-client setups, making it hard to transition.

From 4.0 onwards, the config structure was unified: all clients are declared under a named key map regardless of count, and exactly one must be designated as the autowiring default.

Decision

The config tree uses useAttributeAsKey('name') + arrayPrototype() so every client has a name (e.g., main, preview, brand_a). A default: bool flag marks which client gets the Symfony autowiring aliases (ClientInterface, Client, contentful.delivery.client).

Invariant enforced at compile time: exactly one client must have default: true. If only one client is configured, ContentfulExtension automatically sets default: true on it. If multiple clients are configured without exactly one default, a LogicException is thrown during container:build.

Consequences

• Single-client apps require no default key in config (auto-set)
• Multi-client apps must explicitly designate one default — this is a pit-of-success design
• The UPGRADE-4.0.md guide explains the migration from the pre-4.0 structure
• Non-default clients are accessible by their service ID (contentful.delivery.{name}_client) but not by autowiring type hint alone