Docker Laravel Package

Product Decisions This Supports

• Test Infrastructure Modernization: Enables seamless integration of Dockerized services (e.g., databases, APIs, or legacy systems) into PHPUnit tests, reducing flakiness and dependency on shared environments.
• Build vs. Buy: Avoids reinventing Docker orchestration logic for test suites, leveraging a battle-tested, MIT-licensed solution with minimal maintenance overhead.
• CI/CD Optimization: Accelerates test execution by spinning up isolated, disposable containers per test run, improving parallelization and reducing CI/CD pipeline bottlenecks.
• Roadmap for Observability: Supports future initiatives like test-driven infrastructure validation (e.g., verifying container health before test execution).
• Multi-Environment Testing: Facilitates testing against multiple database versions, OS configurations, or service stacks without manual Docker setup.

When to Consider This Package

• Adopt if:

  • Your PHPUnit tests require Dockerized dependencies (e.g., PostgreSQL, Redis, or custom services).
  • You need to dynamically spin up/down containers per test suite or test case (e.g., for ephemeral environments).
  • Your team lacks DevOps resources to manage Docker orchestration manually or via scripts.
  • You prioritize reproducibility and isolation over shared test environments (e.g., local Docker Desktop or CI-hosted containers).
  • Your stack includes Laravel or other PHP frameworks where Spatie’s packages are already adopted (reduces integration friction).

• Look elsewhere if:

  • Your tests don’t require Docker (e.g., pure unit tests with no external dependencies).
  • You’re using Kubernetes or serverless for test environments (this package is Docker-specific).
  • Your team has dedicated DevOps tools (e.g., Testcontainers for Java/Python) already integrated.
  • You need advanced Docker networking (e.g., custom bridge setups) beyond basic container execution.
  • Your CI/CD pipeline already manages containers (e.g., pre-built images), making this package redundant.

How to Pitch It (Stakeholders)

For Executives: "This package lets us automate Docker container management directly in our PHP test suites—eliminating manual setup, reducing CI/CD costs, and ensuring tests run in consistent, isolated environments. For example, we can test against PostgreSQL 15 and 16 in the same pipeline without extra infrastructure. It’s a low-risk, high-reward way to modernize our test infrastructure, with minimal dev overhead since it’s maintained by Spatie (the same team behind Laravel-friendly packages like Laravel-Permission)."

For Engineering/DevOps: *"Spatie’s Docker package gives us a PHP-native way to start/stop containers in tests, with a clean API:

$container = DockerContainer::create('postgres:15')->start();
$container->execute('psql -c \"SELECT 1\"'); // Test queries

• Pros:
  • No need to write Bash scripts or Docker CLI calls.
  • Works seamlessly with PHPUnit (e.g., @beforeTest setup).
  • MIT-licensed, actively maintained (last release: Nov 2025).
• Use Cases:
  • Spin up databases/services per test suite (e.g., for migration tests).
  • Replace shared test environments with disposable containers.
  • Integrate with Laravel’s testing helpers for end-to-end flows.
• Trade-offs:
  • Adds ~5MB to your vendor directory (negligible for most projects).
  • Requires Docker daemon access (but most CI/CD systems already provide this).
• Next Steps: I recommend a proof-of-concept with our most flaky test suite to demonstrate the impact on reliability and speed."*