Creating Reproducible PHP Tests with Docker Compose

Docker Compose can run a pinned PHP test image alongside disposable test dependencies.

What It Does and When to Use It

Pin the PHP runtime instead of inheriting the host PHP version. A build artifact contains immutable application code, while production configuration and secrets are injected at runtime.

Requirements, Inputs and Expected Behavior

Confirm the runtime, extension, environment variables, and permissions before running the examples in production. A test must wait for a ready database, not merely a started container.

Example 1: Basic Operation

Pin the PHP runtime instead of inheriting the host PHP version.

services:
  tests:
    image: php:8.4-cli
    working_dir: /app
    volumes:
      - ./:/app:ro
    command: ["php", "-l", "tests/SmokeTest.php"]

Example 2: Behavior and Validation

Start an ephemeral test container and remove it afterward.

docker compose run --rm tests
docker compose down --remove-orphans

Practical Example: Application Use

Wait for a healthy database; the test image must provide the PDO driver and PHPUnit.

services:
  database:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: test-only-password
      POSTGRES_DB: app_test
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      retries: 20
  tests:
    build: .
    depends_on:
      database:
        condition: service_healthy
    command: ["vendor/bin/phpunit"]

Important Behavior and Edge Cases

The second example highlights: Start an ephemeral test container and remove it afterward. The practical example adds: Wait for a healthy database; the test image must provide the PDO driver and PHPUnit.

Comparison with Related Approaches

Approach	What changes
Local build and production deployment	A build artifact contains immutable application code, while production configuration and secrets are injected at runtime.
Choosing safely	Pin base images and dependencies and require a health-check before routing traffic.

Common Beginner Mistakes

Mistake	Correct approach
Assuming successful execution proves the result is usable	Check the return value, required extension, and observable output of the specific operation.
Ignoring runtime and environment differences	Verify PHP version, SAPI, operating system, service access, and permissions before deployment.
Skipping operational constraints	A test must wait for a ready database, not merely a started container.

Key Takeaways

Docker Compose can run a pinned PHP test image alongside disposable test dependencies.
Wait for a healthy database; the test image must provide the PDO driver and PHPUnit.
Pin base images and dependencies and require a health-check before routing traffic.