ADR-0001: Symfony Bundle Pattern for Contentful PHP Integration

Status

Accepted

Context

The Contentful PHP Delivery SDK (contentful/contentful) is a standalone library with no Symfony-specific integration. Symfony applications need a way to configure, wire, and inject Contentful clients without boilerplate in each project. Two integration approaches exist:

1. Standalone service file — a simple services.yaml snippet that users copy into their projects
2. Symfony Bundle — a first-class bundle that hooks into the DI container, config system, CLI, cache, and profiler

The bundle pattern is the idiomatic Symfony approach for vendor integrations (DoctrineBundle, MonologBundle, etc.) and enables deep framework integration that a service snippet cannot provide.

Decision

Implement as a symfony-bundle (type in composer.json), extending Symfony\Component\HttpKernel\Bundle\Bundle. The bundle:

• Provides a ContentfulExtension that processes a custom config tree (contentful.delivery.*)
• Registers all services programmatically (no XML/YAML service files in the bundle itself)
• Hooks into the Symfony profiler, cache warm/clear lifecycle, and CLI commands
• Registers itself with Symfony Flex so it can be auto-configured via composer require

Consequences

• Users get zero-boilerplate DI integration: one YAML config block and one bundles.php line
• The bundle has a hard dependency on symfony/framework-bundle (not just individual Symfony components)
• Symfony major version upgrades (e.g., 5→6→7) require bundle updates to track deprecations
• The bundle version major tracks the Symfony major it supports (7.x bundle → Symfony 5.4/6/7)