Weave Code
Docker Laravel Package
spatie/docker
Start and manage Docker containers from PHP. Create and run containers, execute commands inside them, and capture output. Customize behavior like daemonization, auto-cleanup on exit, and privileged mode for more control.
Manage docker containers with PHP
Frequently asked questions about Docker
- How do I start a Docker container from a PHP Laravel test using spatie/docker?
- Use `DockerContainer::create('image-name')->start()` to launch a container. For example, `$container = DockerContainer::create('postgres:15')->start()` starts a PostgreSQL container. The container will auto-cleanup after exiting unless you call `doNotCleanUpAfterExit()`.
- Can I execute commands inside a running Docker container with this package?
- Yes. After starting a container, use `$container->execute('command')` to run commands. Capture output with `$process->getOutput()` or check exit codes with `$process->getExitCode()`. Example: `$container->execute('whoami')->getOutput()`.
- Does spatie/docker work with Laravel’s PHPUnit testing environment?
- Absolutely. Start containers in `setUp()` and stop them in `tearDown()` to ensure isolation. Example: `public function setUp(): void { $this->container = DockerContainer::create('redis:7')->start(); }`. Pair with Laravel’s database testing utilities for full-stack tests.
- What Laravel versions and PHP versions does spatie/docker support?
- The package supports PHP 8.1+ and is optimized for Laravel 9+. It lacks Laravel-specific features like a ServiceProvider but integrates seamlessly with Laravel’s Service Container via the `DockerContainer` facade. Tested with Laravel 9/10.
- How do I prevent containers from being cleaned up after tests?
- Call `doNotCleanUpAfterExit()` on the container instance before starting it. Example: `DockerContainer::create('mysql:8')->doNotCleanUpAfterExit()->start()`. Useful for debugging or shared containers across test suites, but be mindful of resource usage.
- Will spatie/docker work in GitHub Actions CI/CD pipelines?
- Yes, but ensure Docker is installed in your CI environment. Use GitHub’s `docker/setup-qemu-action` to pull images. Example workflow step: `services: docker: docker://dind`. Spatie/docker is ideal for isolated test environments where containers are ephemeral.
- Can I run containers in privileged mode for advanced operations?
- Yes. Use `privileged()` to grant extended permissions. Example: `DockerContainer::create('alpine')->privileged()->start()`. This is useful for containers needing access to host devices or kernel features, but use cautiously in CI/CD to avoid security risks.
- How do I handle timeouts or hanging containers in tests?
- The package doesn’t enforce timeouts by default, but you can wrap container operations in PHP’s `exec()` with timeouts or use Laravel’s `Artisan::timeout()` for test commands. For Docker-specific timeouts, consider setting `--timeout` in the container’s CLI command or using Docker’s native `--max-retry-count`.
- Is spatie/docker suitable for production workloads, or just testing?
- This package is designed for short-lived, disposable containers—ideal for tests and CI/CD. Avoid using it for production workloads due to lack of built-in orchestration, scaling, or persistent storage management. For production, use Docker Compose or Kubernetes.
- What are the alternatives to spatie/docker for Laravel Docker management?
- For Laravel, consider `laravel/sail` for local development or `testcontainers/php` (a PHP port of Java’s Testcontainers) for advanced test setups. `docker-compose` is another option, but spatie/docker offers a more fluent, PHP-native API for container lifecycle management in tests.
Weaver
How can I help you explore Laravel packages today?