{"id":13549001,"url":"https://github.com/spatie/docker","last_synced_at":"2025-05-15T20:07:14.678Z","repository":{"id":37024653,"uuid":"237437425","full_name":"spatie/docker","owner":"spatie","description":"Manage docker containers with PHP","archived":false,"fork":false,"pushed_at":"2024-05-27T09:46:02.000Z","size":132,"stargazers_count":467,"open_issues_count":1,"forks_count":58,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-05-15T20:06:26.797Z","etag":null,"topics":["docker","php"],"latest_commit_sha":null,"homepage":"https://spatie.be/open-source","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spatie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":"https://spatie.be/open-source/support-us"}},"created_at":"2020-01-31T13:38:25.000Z","updated_at":"2025-05-15T08:56:36.000Z","dependencies_parsed_at":"2023-12-18T15:48:30.004Z","dependency_job_id":"6f8fc62d-83b0-48f9-b513-046966065095","html_url":"https://github.com/spatie/docker","commit_stats":{"total_commits":157,"total_committers":28,"mean_commits":5.607142857142857,"dds":0.5859872611464968,"last_synced_commit":"f17d4736d98f8aeca6d98346907fd4509d5541c1"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Fdocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Fdocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Fdocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Fdocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatie","download_url":"https://codeload.github.com/spatie/docker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414501,"owners_count":22067272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","php"],"created_at":"2024-08-01T12:01:17.131Z","updated_at":"2025-05-15T20:07:09.620Z","avatar_url":"https://github.com/spatie.png","language":"PHP","funding_links":["https://spatie.be/open-source/support-us"],"categories":["PHP"],"sub_categories":[],"readme":"# Manage docker containers with PHP\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/docker.svg?style=flat-square)](https://packagist.org/packages/spatie/docker)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/spatie/docker/run-tests.yml?label=tests)](https://github.com/spatie/docker/actions?query=workflow%3Arun-tests+branch%3Amaster)\n[![Total Downloads](https://img.shields.io/packagist/dt/spatie/docker.svg?style=flat-square)](https://packagist.org/packages/spatie/docker)\n\nThis package provides a nice way to start docker containers and execute commands on them.\n\n````php\n$containerInstance = DockerContainer::create($imageName)-\u003estart();\n\n$process = $containerInstance-\u003eexecute('whoami');\n\n$process-\u003egetOutput(); // returns the name of the user inside the docker container\n````\n\n## Support us\n\n[\u003cimg src=\"https://github-ads.s3.eu-central-1.amazonaws.com/docker.jpg?t=1\" width=\"419px\" /\u003e](https://spatie.be/github-ad-click/docker)\n\nWe invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).\n\nWe highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require spatie/docker\n```\n\n## Usage\n\nYou can get an instance of a docker container using\n\n```php\n$containerInstance = DockerContainer::create($imageName)-\u003estart();\n```\n\nBy default the container will be daemonized and it will be cleaned up after it exists.\n\n### Customizing the docker container\n\n#### Prevent daemonization\n\nIf you don't want your docker being daemonized, call `doNotDaemonize`.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003edoNotDaemonize()\n    -\u003estart();\n```\n\n#### Prevent automatic clean up\n\nIf you don't want your docker being cleaned up after it exists, call `doNotCleanUpAfterExit`.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003edoNotCleanUpAfterExit()\n    -\u003estart();\n```\n\n#### Priviliged\n\nIf you want your docker being privileged, call `privileged`.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003eprivileged()\n    -\u003estart();\n```\n\n#### Custom shell\n\nIf the `bash` shell is not available in your docker image, you can specify an alternative shell.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003eshell('sh')\n    -\u003estart();\n```\n\n#### Custom docker binary\n\nIf the `docker` binary is not globally available, you can specify the exact path.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003edockerBin('/usr/local/bin/docker')\n    -\u003estart();\n```\n\n#### Naming the container\n\nYou can name the container by passing the name as the second argument to the constructor.\n\n```php\nnew DockerContainer($imageName, $nameOfContainer);\n```\n\nAlternatively, use the `name` method.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003ename($yourName)\n    -\u003estart();\n```\n\n#### Mapping ports\n\nYou can map ports between the host machine and the docker container using the `mapPort` method. To map multiple ports, just call `mapPort` multiple times.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003emapPort($portOnHost, $portOnContainer)\n    -\u003emapPort($anotherPortOnHost, $anotherPortOnContainer)\n    -\u003estart();\n```\n\nThe default protocol for the port mapping is TCP. If you want to use UDP, you can pass it as the third argument.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003emapPort($portOnHost, $portOnContainer, 'udp')\n    -\u003estart();\n```\n\n#### Environment variables\n\nYou can set environment variables using the `setEnvironmentVariable` method. To add multiple arguments, just call `setEnvironmentVariable` multiple times.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003esetEnvironmentVariable($variableKey, $variableValue)\n    -\u003esetEnvironmentVariable($anotherVariableKey, $anotherVariableValue)\n    -\u003estart();\n```\n\n#### Setting Volumes\n\nYou can set volumes using the `setVolume` method. To add multiple arguments, just call `setVolume` multiple times.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003esetVolume($pathOnHost, $pathOnDocker)\n    -\u003esetVolume($anotherPathOnHost, $anotherPathOnDocker)\n    -\u003estart();\n```\n\n#### Setting Labels\n\nYou can set labels using the `setLabel` method. To add multiple arguments, just call `setLabel` multiple times.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003esetLabel($labelName, $labelValue)\n    -\u003esetLabel($anotherLabelName, $anotherLabelValue)\n    -\u003estart();\n```\n\n#### Adding Commands\n\nYou can add commands using the `setCommands` method.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003esetCommands('--api.insecure=true', '--providers.docker=true')\n    -\u003estart();\n```\nThese commands will be placed at the end of to the `docker run` command.\n\n#### Add optional arguments\n\nIf you want to add optional arguments to the `docker run` command, use `setOptionalArgs` method:\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003esetOptionalArgs('-it', '-a')\n    -\u003estart();\n```\nThese arguments will be placed after `docker run` immediately.\n\n\n#### Automatically stopping the container after PHP exists\n\nWhen using this package in a testing environment, it can be handy that the docker container is stopped after `__destruct` is called on it (mostly this will happen when the PHP script ends). You can enable this behaviour with the `stopOnDestruct` method.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003estopOnDestruct()\n    -\u003estart();\n```\n\n#### Attaching a network to the container\n\nIf you want to attach the container to a docker network, use `network` method:\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003enetwork('my-network')\n    -\u003estart();\n```\n\n#### Specify a remote docker host for execution\n\nYou can set the host used for executing the container. The `docker` command line accepts a daemon socket string. To connect to a remote docker host via ssh, use the syntax `ssh://username@hostname`. Note that the proper SSH keys will already need to be configured for this work.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003eremoteHost('ssh://username@hostname')\n    -\u003estart();\n```\n\n#### Specify an alternative command to execute\n\nUpon startup of a container, docker will execute the command defined within the container. The `command` method gives the ability to override to default command to run within the container.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003ecommand('ls -l /etc')\n    -\u003estart();\n```\n\n#### Getting the start command string\n\nYou can get the string that will be executed when a container is started with the `getStartCommand` function\n\n```php\n// returns \"docker run -d --rm spatie/docker\"\nDockerContainer::create($imageName)-\u003egetStartCommand();\n```\n\n#### Changing the start command timeout\n\nYou can change the timeout for the start command with the `setStartCommandTimeout` function _(the default is 60s)_.\n\n```php\n$containerInstance = DockerContainer::create($imageName)\n    -\u003esetStartCommandTimeout(120)\n    -\u003estart();\n```\n\n### Available methods on the docker container instance\n\n#### Executing a command\n\nTo execute a command on the container, use the `execute` method.\n\n```php\n$process = $instance-\u003eexecute($command);\n```\n\nYou can execute multiple command in one go by passing an array.\n\n```php\n$process = $instance-\u003eexecute([$command, $anotherCommand]);\n```\n\nTo change the process timeout you can pass a second parameter to the `execute` method _(the default is 60s)_.\n\n```php\n$process = $instance-\u003eexecute($command, 3600);\n```\n\nThe execute method returns an instance of [`Symfony/Process`](https://symfony.com/doc/current/components/process.html).\n\nYou can check if your command ran successfully using the `isSuccessful` $method\n\n```php\n$process-\u003eisSuccessful(); // returns a boolean\n```\n\nYou can get to the output using `getOutput()`. If the command did not run successfully, you can use `getErrorOutput()`. For more information on how to work with a `Process` head over to [the Symfony docs](https://symfony.com/doc/current/components/process.html).\n\n#### Installing a public key\n\nIf you cant to connect to your container instance via SSH, you probably want to add a public key to it.\n\nThis can be done using the `addPublicKey` method.\n\n```php\n$instance-\u003eaddPublicKey($pathToPublicKey);\n```\n\nIt is assumed that the `authorized_keys` file is located in at `/root/.ssh/authorized_keys`. If this is not the case, you can specify the path of that file as a second parameter.\n\n```php\n$instance-\u003eaddPublicKey($pathToPublicKey, $pathToAuthorizedKeys);\n```\n\nNote that in order to be able to connect via SSH, you should set up a SSH server in your `dockerfile`. Take a look at the `dockerfile` in the tests of this package for an example.\n\n#### Adding files to your instance\n\nFiles can be added to an instance with `addFiles`.\n\n```php\n$instance-\u003eaddFiles($fileOrDirectoryOnHost, $pathInContainer);\n```\n\n#### Get the docker inspect information\n\nThe json decoded array from the docker inspect command can be retrieved with `inspect`.\n\n```php\n$inspectArray = $instance-\u003einspect();\n$inspectArray[0]['State']['Status']; // Running, Starting etc.\n$inspectArray[0]['RestartCount']; // Integer\n$inspectArray[0]['NetworkSettings']['IPAddress']; // 172.17.0.2\n```\n\n#### Adding other functions on the docker instance\n\nThe `Spatie\\Docker\\ContainerInstance` class is [macroable](https://github.com/spatie/macroable). This means you can add extra functions to it.\n\n````php\nSpatie\\Docker\\DockerContainerInstance::macro('whoAmI', function () {\n    $process = $containerInstance-\u003erun('whoami');\n\n\n    return $process-\u003egetOutput();\n});\n\n$containerInstance = DockerContainer::create($imageName)-\u003estart();\n\n$containerInstance-\u003ewhoAmI(); // returns of name of user in the docker container\n````\n\n### Testing\n\nBefore running the tests for the first time, you must build the `spatie/docker` container with:\n\n````bash\ncomposer build-docker\n````\n\nNext, you can run the tests with:\n``` bash\ncomposer test\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.\n\n## Security\n\nIf you've found a bug regarding security please mail [security@spatie.be](mailto:security@spatie.be) instead of using the issue tracker.\n\n## Credits\n\n- [Ruben Van Assche](https://github.com/rubenvanassche)\n- [Freek Van der Herten](https://github.com/freekmurze)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Fdocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatie%2Fdocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Fdocker/lists"}