Save this content to: AGENTS.md

---
package: contentful/contentful-bundle
source_path: AGENTS.md
repo: https://github.com/contentful/ContentfulBundle
---

# Agent Guide

<!-- Generated by seed-golden-context | Last updated: 2026-05-11 -->

Read this file first. It tells you where to find context in this repo.

## Quick Reference

| What you need | Where to look |
|---|---|
| How this repo is structured | [ARCHITECTURE.md](./ARCHITECTURE.md) |
| How to build/test/run | [CONTRIBUTING.md](./CONTRIBUTING.md) |
| Why decisions were made | [docs/ADRs/](./docs/ADRs/) |
| What this repo does | [README.md](./README.md) |
| PR review rules | [.bito/guidelines/](./.bito/guidelines/) |
| Active specs/work | [docs/specs/](./docs/specs/) |

## Sharp Edges & Invariants

- **Exactly one default client.** `ContentfulExtension` throws `LogicException` at container compile time if the number of clients marked `default: true` is not exactly 1. When only one client is configured, it is implicitly default — do not add a second without also setting one as `default: false`.
- **`master` is the default branch**, not `main`. All PRs and release cuts target `master`.
- **This bundle is CDA/Preview only.** It wraps `contentful/contentful` (Delivery SDK). It does not and should not touch the Content Management API (CMA) — that is out of scope.
- **`ProfilerController` is conditionally registered.** It only exists at runtime if both `profiler` and `twig` services are present in the container (checked in `ProfilerControllerPass`). Do not assume it is always available.
- **Cache is opt-in.** Neither resource cache nor query cache is enabled by default. Do not add default cache pool wiring — the user must explicitly configure `options.cache.pool` or `options.query_cache.pool`.
- **Query cache has no invalidation mechanism.** `options.query_cache.lifetime` defaults to 60 seconds. Do not raise this default — stale content risk is the documented trade-off.
- **`SymfonyIntegration` reports telemetry.** `ClientFactory` calls `$client->useIntegration(new SymfonyIntegration())` on every client created. Do not remove this — it's how Contentful tracks framework adoption in SDK telemetry.
- **No Symfony Flex recipe is maintained here.** The old Flex recipe (copy config, register bundle, add `.env` vars) may be stale. Do not assume Flex auto-configuration works without verification.
- **PHP version matrix.** `composer.json` `require` declares `^7.4|^8.0` (PHP 7.4 and 8.x are the declared supported range). CI only validates PHP 8.0–8.4 — there is no PHP 7.4 job in `.circleci/config.yml`. PHP 7.4 is declared supported but not actively tested in CI. Do not drop PHP 7.4 from `composer.json` without a major version bump and changelog entry.
- **Static analysis is level 4** (PHPStan). Do not lower it. Two `@phpstan-ignore-line` comments exist in `Configuration.php` for a known PHPStan limitation with chained node builders — these are intentional.

## Key Conventions

- **Commit format:** no enforced tooling, but conventional commit style preferred (`feat:`, `fix:`, `chore:`, `docs:`)
- **Branch strategy:** `master` + feature branches, no `develop` branch
- **Test location:** `tests/Unit/` mirrors `src/` structure 1:1
- **Release:** manual via `composer run release`, tagged, published to Packagist
- **Code style:** enforced by `php-cs-fixer` (config in `.php-cs-fixer.php`)

## Integration Points

**Upstream (this repo consumes):**
- `contentful/contentful` — Contentful PHP CDA SDK (the actual API client)
- `symfony/framework-bundle` — DI container, kernel, profiler, cache interfaces
- `psr/log` + `psr/cache` — standards interfaces for logger and cache pool injection
- Contentful CDA (`cdn.contentful.com`) + Preview API (`preview.contentful.com`) — fetched by the SDK

**Downstream (consumes this repo):**
- Any Symfony 5.4/6/7 application requiring Contentful content delivery

## Build & Quality

```bash
# Quick verification loop
composer install && composer test-quick-fail && composer lint-static-analysis
```