PHPackages diego-ninja/docker - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [DevOps & Deployment](/categories/devops) 4. / 5. diego-ninja/docker ActiveLibrary[DevOps & Deployment](/categories/devops) diego-ninja/docker ================== Run and manage docker containers in your php code v2.1.0(5mo ago)02.2k↓66.7%MITPHPPHP ^8.4CI passing Since Nov 3Pushed 5mo agoCompare [ Source](https://github.com/diego-ninja/docker)[ Packagist](https://packagist.org/packages/diego-ninja/docker)[ Docs](https://github.com/diego-ninja/docker)[ Fund](https://paypal.me/diegorin)[ Fund](https://www.buymeacoffee.com/diegoninja)[ RSS](/packages/diego-ninja-docker/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (6)Dependencies (16)Versions (8)Used By (0) 🐋 Docker for PHP ================ [](#-docker-for-php) [![Latest Version on Packagist](https://camo.githubusercontent.com/08bffa608e20de614b29ee98576a264361f119e6493917f5be33b01f4d7b8335/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f646965676f2d6e696e6a612f646f636b65722e7376673f7374796c653d666c61742d73717561726526636f6c6f723d626c7565266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)](https://packagist.org/packages/diego-ninja/docker)[![Total Downloads](https://camo.githubusercontent.com/c6b45f9e02fc63283a352fe5309062c9f7220f5096b9ded433900dd179fdabc3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f646965676f2d6e696e6a612f646f636b65722e7376673f7374796c653d666c61742d73717561726526636f6c6f723d626c7565266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)](https://packagist.org/packages/diego-ninja/docker)[![PHP Version](https://camo.githubusercontent.com/0b083ef1133eb01a8bde9257d4d998565e5862d370eff2097b81889f9c9a8230/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f646965676f2d6e696e6a612f646f636b65722e7376673f7374796c653d666c61742d73717561726526636f6c6f723d626c7565266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)](https://camo.githubusercontent.com/0b083ef1133eb01a8bde9257d4d998565e5862d370eff2097b81889f9c9a8230/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f646965676f2d6e696e6a612f646f636b65722e7376673f7374796c653d666c61742d73717561726526636f6c6f723d626c7565266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)[![License: MIT](https://camo.githubusercontent.com/a26a213b909339a4120989779b78a923195a74e3915f6e0f0c619bd9f3d23208/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e7376673f7374796c653d666c61742d73717561726526636f6c6f723d626c7565266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)](https://opensource.org/licenses/MIT)[![GitHub last commit](https://camo.githubusercontent.com/6fa2269a3e27c4c75e46a5f095e1c504769a24dd11a7175f3c2c79f9a3d9c923/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f646965676f2d6e696e6a612f646f636b65723f7374796c653d666c61742d73717561726526636f6c6f723d626c7565266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)](https://camo.githubusercontent.com/6fa2269a3e27c4c75e46a5f095e1c504769a24dd11a7175f3c2c79f9a3d9c923/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f646965676f2d6e696e6a612f646f636b65723f7374796c653d666c61742d73717561726526636f6c6f723d626c7565266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)[![wakatime](https://camo.githubusercontent.com/b1bfca6790d2c99b370428ffb5f189a36ad58df1af899712a886d4ff2c6865fc/68747470733a2f2f77616b6174696d652e636f6d2f62616467652f757365722f62643635663035352d633966332d346637332d393261612d3363393831306637306363332f70726f6a6563742f37633931653562612d623566622d343165312d383639322d3062623661326631653065362e7376673f7374796c653d666c61742d73717561726526636f6c6f723d626c7565266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)](https://wakatime.com/badge/user/bd65f055-c9f3-4f73-92aa-3c9810f70cc3/project/3cc2ec60-a8b4-4ddc-aeac-ea78e37a094b) ![Tests](https://camo.githubusercontent.com/070abb14f999a78f9d49a2a36673ca0e3322b7b529e01bb749e7562e21e18459/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f646965676f2d6e696e6a612f646f636b65722f72756e2d74657374732e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265266c6f676f3d676974687562266c6162656c3d7465737473266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)![Static Analysis](https://camo.githubusercontent.com/59a6f7ea52327c52a2e52ec6c94641e12621f529294f1a3808c707fc7dd2b34b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f646965676f2d6e696e6a612f646f636b65722f7374617469632d636f64652d616e616c797369732e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265266c6f676f3d676974687562266c6162656c3d7068707374616e2532303130266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)![Code Style](https://camo.githubusercontent.com/8e9a3f9a0c2e557f5f186e86186ea765b39fdc2a817aa0f0051ce87e75980f81/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f646965676f2d6e696e6a612f646f636b65722f7068702d63732d66697865722e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265266c6f676f3d676974687562266c6162656c3d7374796c65253341253230504552266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530)![Coveralls](https://camo.githubusercontent.com/fae83a969879c471eb55bd318b761f73b7b4c80c309adb06cd188306f0b5a3e9/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c73436f7665726167652f6769746875622f646965676f2d6e696e6a612f646f636b65723f6272616e63683d6d61696e267374796c653d666c61742d737175617265266c6f676f3d636f766572616c6c73266c6f676f436f6c6f723d253233393439636134266c6162656c436f6c6f723d253233336634373530266c696e6b3d6874747073253341253246253246636f766572616c6c732e696f253246676974687562253246646965676f2d6e696e6a61253246646f636b6572) This package provides a fluent, modern API to start and manage Docker containers directly from your PHP code. It is a fork of `spatie/docker` with significant improvements in ergonomics, security, and functionality. Key Features ------------ [](#key-features) - ✅ **Ergonomic Facade API**: A static `Docker` facade that simplifies container creation (`Docker::nginx()->start()`). - ✅ **Type-Safe**: Thanks to PHP 8.4 and the intensive use of immutable Value Objects (`ImageName`, `ContainerPath`, `Port`) to validate all inputs. - ✅ **Secure**: Prevents command injection by validating all parameters through Value Objects. - ✅ **SSH Agent Forwarding**: Securely allows containers to access the host's SSH keys. - ✅ **Extensible**: Register your own custom services on the `Facade` to reuse configurations. - ✅ **Well-Tested**: Over 95% test coverage. Installation ------------ [](#installation) You can install the package via Composer. It requires PHP 8.4 or higher. ``` composer require diego-ninja/docker ``` Quick Start ----------- [](#quick-start) The easiest way to use the package is through the `Docker` facade. ``` use Ninja\Docker\Docker; // Start a Nginx container on port 8080 $container = Docker::image('nginx:latest') ->port(8080, 80) ->name('my-nginx') ->start(); echo "Container started. IP: " . $container->getIp() . "\n"; // Execute a command inside the container $output = $container->execute('ls -la /usr/share/nginx/html'); echo $output; // Stop and remove the container $container->stop(); ``` Key Differences with `spatie/docker` ------------------------------------ [](#key-differences-with-spatiedocker) This package is a fork of [spatie/docker](https://github.com/spatie/docker), but it introduces significant improvements: 1. **Facade for a Simplified API**: The `Docker` facade provides a static, expressive, and easy-to-remember API, ideal for frameworks like Laravel or for quick usage. ``` // Before (and still works) (new DockerContainer('nginx:latest'))->port(8080, 80)->start(); // Now (recommended) Docker::image('nginx:latest')->port(8080, 80)->start(); ``` 2. **Type Safety with Value Objects**: Instead of using raw strings and numbers, the library uses Value Objects to validate every parameter, preventing common errors and attacks. ``` // Encourages using Value Objects for clarity and safety use Ninja\Docker\ValueObjects\HostPath; use Ninja\Docker\ValueObjects\ContainerPath; Docker::image('...')->volume( HostPath::from(__DIR__ . '/content'), ContainerPath::from('/usr/share/nginx/html') ); ``` 3. **Specific Exceptions**: More descriptive exceptions, like `CouldNotStartDockerContainer`, have been added to make debugging easier. Detailed Usage -------------- [](#detailed-usage) ### 1. Using the Facade (Recommended) [](#1-using-the-facade-recommended) The `Docker` facade offers three ways to create containers: #### a) Shortcuts for Common Services [](#a-shortcuts-for-common-services) It includes shortcuts for the most popular services with pre-defined configurations. ``` // Nginx on port 80 Docker::nginx()->start(); // MySQL 8 with a root password Docker::mysql(['password' => 'secret'])->start(); // PostgreSQL 16 with a password Docker::postgres(['password' => 'secret', 'database' => 'my_app'])->start(); // Redis Docker::redis()->start(); ``` You can pass a configuration array to customize the service: ``` // MySQL with a database, user, and persistent data directory Docker::mysql([ 'password' => 'root_secret', 'database' => 'my_app', 'user' => 'app_user', 'user_password' => 'user_pass', 'data_dir' => '/path/on/host/for/data', // Volume mount for persistence 'port' => 3307, // Custom host port ])->start(); ``` #### b) Generic `container()` Builder [](#b-generic-container-builder) For any image that doesn't have a shortcut, use the `container()` method. ``` Docker::container('alpine:latest') ->command('sleep', '300') // Keeps the container running ->start(); ``` #### c) Registering Custom Services [](#c-registering-custom-services) You can register your own shortcuts, for example, in your application's bootstrap file. ``` // Register a service once Docker::register('mailhog', [ 'image' => 'mailhog/mailhog', 'ports' => [1025 => 1025, 8025 => 8025], 'name_prefix' => 'mailhog', ]); // Use it anywhere in your code Docker::mailhog()->start(); ``` ### 2. Fluent API [](#2-fluent-api) All facade methods return a `DockerContainer` instance, so you can continue to use the fluent API to override or add configurations. ``` Docker::mysql(['password' => 'secret']) ->port(3307, 3306) // Override the default port ->namedVolume('mysql-data', '/var/lib/mysql') // Use a named volume ->network('backend') // Add to a network ->start(); ``` ### 3. Configuration Examples [](#3-configuration-examples) #### Port Mapping [](#port-mapping) Use `port(hostPort, containerPort)`. ``` ->port(8080, 80) ``` #### Volume Mapping [](#volume-mapping) - **Bind Mount**: Mounts a host path into the container. ``` use Ninja\Docker\ValueObjects\HostPath; use Ninja\Docker\ValueObjects\ContainerPath; ->volume(HostPath::from('/path/on/host'), ContainerPath::from('/path/in/container')) ``` - **Named Volume**: Uses a Docker-managed volume. ``` use Ninja\Docker\ValueObjects\VolumeName; use Ninja\Docker\ValueObjects\ContainerPath; ->namedVolume(VolumeName::from('my-volume'), ContainerPath::from('/path/in/container')) ``` #### Environment Variables [](#environment-variables) ``` ->environment('MY_VAR', 'its_value') ->environment('ANOTHER_VAR', 'another_value') ``` ### 4. Interacting with Running Containers [](#4-interacting-with-running-containers) The `start()` method returns a `DockerContainerInstance`. ``` $container = Docker::nginx()->start(); // Get the container's IP address $ip = $container->getIp(); // Execute a command $output = $container->execute('whoami'); // returns "root" // Get the container ID $id = $container->getContainerId(); // Check if it's running if ($container->isRunning()) { // ... } // Stop the container $container->stop(); ``` You can also connect to an already running container. ``` $container = DockerContainerInstance::fromExisting('my-nginx'); $container->execute('echo "Hello from an existing container"'); ``` Testing ------- [](#testing) Before running the tests for the first time, you need to build the Docker image for testing: ``` composer build-docker ``` Then, you can run the full test suite with [Pest](https://pestphp.com/): ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see `CONTRIBUTING.md` for details. Contributions are welcome. Security -------- [](#security) If you've found a security vulnerability, please email instead of using the issue tracker. Credits ------- [](#credits) - [Diego Rin Martin](https://github.com/diego-ninja) - [Ruben Van Assche](https://github.com/rubenvanassche) - [Freek Van der Herten](https://github.com/freekmurze) License ------- [](#license) The MIT License (MIT). Please see the [License File](LICENSE.md) for more information. ### Health Score 46 — FairBetter than 93% of packages Maintenance70 Regular maintenance activity Popularity17 Limited adoption so far Community18 Small or concentrated contributor base Maturity68 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~222 days Recently: every ~197 days Total 6 Last Release 176d ago Major Versions v1.0.3 → v2.0.02025-11-20 PHP version history (3 changes)v1.0.0PHP ^8.0 v1.0.1PHP ^8.2 v2.0.0PHP ^8.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/dff5b0a76de3d555cb236c400384058ba23982bce2e859cc1b2f0c1f0161a3e6?d=identicon)[diego.ninja](/maintainers/diego.ninja) --- Top Contributors [![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (109 commits)")[![diego-ninja](https://avatars.githubusercontent.com/u/78662279?v=4)](https://github.com/diego-ninja "diego-ninja (81 commits)")[![rubenvanassche](https://avatars.githubusercontent.com/u/619804?v=4)](https://github.com/rubenvanassche "rubenvanassche (18 commits)")[![jbraband](https://avatars.githubusercontent.com/u/1907283?v=4)](https://github.com/jbraband "jbraband (9 commits)")[![patinthehat](https://avatars.githubusercontent.com/u/5508707?v=4)](https://github.com/patinthehat "patinthehat (9 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (8 commits)")[![Galironfydar](https://avatars.githubusercontent.com/u/13006625?v=4)](https://github.com/Galironfydar "Galironfydar (7 commits)")[![jkniest](https://avatars.githubusercontent.com/u/15618191?v=4)](https://github.com/jkniest "jkniest (4 commits)")[![m1guelpf](https://avatars.githubusercontent.com/u/23558090?v=4)](https://github.com/m1guelpf "m1guelpf (3 commits)")[![joelambert](https://avatars.githubusercontent.com/u/644362?v=4)](https://github.com/joelambert "joelambert (3 commits)")[![szepeviktor](https://avatars.githubusercontent.com/u/952007?v=4)](https://github.com/szepeviktor "szepeviktor (2 commits)")[![tiagof](https://avatars.githubusercontent.com/u/1729910?v=4)](https://github.com/tiagof "tiagof (2 commits)")[![maartenpaauw](https://avatars.githubusercontent.com/u/4550875?v=4)](https://github.com/maartenpaauw "maartenpaauw (2 commits)")[![vedelaar](https://avatars.githubusercontent.com/u/41993858?v=4)](https://github.com/vedelaar "vedelaar (2 commits)")[![wajdijurry](https://avatars.githubusercontent.com/u/25797257?v=4)](https://github.com/wajdijurry "wajdijurry (2 commits)")[![AyoobMH](https://avatars.githubusercontent.com/u/37803924?v=4)](https://github.com/AyoobMH "AyoobMH (2 commits)")[![sfolador](https://avatars.githubusercontent.com/u/36632?v=4)](https://github.com/sfolador "sfolador (1 commits)")[![spekulatius](https://avatars.githubusercontent.com/u/8433587?v=4)](https://github.com/spekulatius "spekulatius (1 commits)")[![tomwelch](https://avatars.githubusercontent.com/u/1016558?v=4)](https://github.com/tomwelch "tomwelch (1 commits)")[![fernandokbs](https://avatars.githubusercontent.com/u/17089683?v=4)](https://github.com/fernandokbs "fernandokbs (1 commits)") --- Tags satis-enableddockerninja ### Code Quality TestsPest Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/diego-ninja-docker/health.svg) ``` [![Health](https://phpackages.com/badges/diego-ninja-docker/health.svg)](https://phpackages.com/packages/diego-ninja-docker) ``` ### Alternatives [spatie/docker Run a docker container in your PHPUnit tests 478120.2k12](/packages/spatie-docker)[aschmelyun/fleet Run multiple Laravel Sail websites on your local environment 33269.5k](/packages/aschmelyun-fleet)[ryoluo/sail-ssl Laravel Sail plugin to enable SSL (HTTPS) connection with Nginx. 188672.6k2](/packages/ryoluo-sail-ssl)[testcontainers/testcontainers Testcontainers implementation in PHP 199184.7k17](/packages/testcontainers-testcontainers)[contributte/bootstrap Extra contrib to nette/boostrap 111.5M3](/packages/contributte-bootstrap)[vcian/pulse-docker-monitor A Laravel Pulse card to show docker containers with CPU & Memory Utilization 348.0k](/packages/vcian-pulse-docker-monitor) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)