ADR-0005: Devcontainer-Based Local Dev and CI (DX-822)

Status

Accepted

Context

Prior to this change, each PHP SDK had ad-hoc CI setup using CircleCI with per-job PHP images, and local development required manually installing the correct PHP version, Composer, and extensions. This led to "works on my machine" problems, divergence between local and CI environments, and friction for new contributors and agents trying to reproduce builds.

DX-822 was filed to standardize developer environments across all PHP SDK repos. The goal: a single, repo-local devcontainer configuration that runs identically in VS Code, terminal (via the devcontainer CLI), and GitHub Actions CI.

Decision

Each PHP SDK repo (including this one) received a .devcontainer/ configuration. GitHub Actions CI was updated to use the same devcontainer image via devcontainer up + devcontainer exec steps. This ensures local and CI environments are identical by construction. The PR adding this was #67, announced in prd-alpine-chat (2026-03-21).

The PHP version for devcontainer jobs can be controlled via the PHP_VERSION environment variable passed to devcontainer up.

Consequences

• Enables: Reproducible builds for all contributors and agents; CI/local parity; per-repo PHP version isolation.
• Requires: Docker for local dev; devcontainer CLI (npm install -g [@devcontainers](https://github.com/devcontainers)/cli).
• Trade-off: CI jobs are slower than bare GitHub-hosted runners because each job must build or pull the devcontainer image. This is accepted for the reproducibility benefit.
• Not applicable for host-side tooling: Do not run composer install, phpstan, or php-cs-fixer directly on the host — always use devcontainer exec.