Docker PHP (for lack of a better name) is a Docker client written in PHP. This library aims to reach 100% API support of the Docker Engine.

The version 3.x documentation is available. Its source lives in docs/; see DOCUMENTATION.md to preview and edit it locally. The legacy documentation remains available for earlier releases.

After this repository was archived in 2019, the code was forked in beluga-php/docker-php, where maintenance and improvements continued.

We later contacted joelwurtz and agreed to take over maintenance of the original docker-php/docker-php repository to give you a better upgrade path. Development will continue here, and we will archive beluga-php/docker-php once the migration is complete.

Version 3.0 targets Docker Engine API v1.45. We plan to add the missing API versions and bring support up to the latest Docker Engine API. See Upgrading to 3.0 below for how to migrate from existing releases.

• PHP 8.1 or later, with the mbstring extension.
• Composer.
• Access to a Docker daemon that accepts API v1.45 requests.

composer require "docker-php/docker-php:^3.0"

Composer installs docker-php/docker-php-api as a dependency. The 3.0 release targets Docker API v1.45 and requires the matching generated API package.

<?php

require __DIR__ . '/vendor/autoload.php';

use Docker\Docker;

$docker = Docker::create();

foreach ($docker->containerList(['all' => true]) as $container) {
    printf("%s\t%s\n", $container->getId(), $container->getImage());
}

Endpoint methods return generated models where the API defines a response body. Their PHPDoc lists accepted parameters, return types and API exceptions.

Docker::create() connects through unix:///var/run/docker.sock by default. Environment variables are optional. See connection settings and the Guzzle examples for custom sockets, remote daemons and TLS configuration.

For streaming output, see container logs, command output and the streaming reference. These guides cover callback streams, TTY output and raw response framing.

See the official Docker Engine API v1.45 reference for endpoint descriptions, parameters and response schemas matching this API line.

The client package follows semantic versioning. The generated API package uses Jane-major.Docker-major.Docker-minor.revision: 7.1.45.0 means Docker API 1.45, generated with Jane 7, revision 0.

Keep generated API dependencies within one Docker specification. The 3.0 client uses this range:

"docker-php/docker-php-api": ">=7.1.45.0 <7.1.46.0"

With the default connection factory, DOCKER_API_VERSION overrides the version in request URLs:

DOCKER_API_VERSION=1.52 php your-script.php

Since 3.1.0, the factory's api_version option can pin the request version directly in PHP. It takes precedence over DOCKER_API_VERSION. See connection settings.

The generated endpoints and models still describe API v1.45. Changing the URL version does not add newer API fields or endpoints. The client does not automatically negotiate an API version with the daemon.

Version 3.0 requires PHP 8.1 or later, PSR-7 v2 and Jane 7-generated models. Review endpoint signatures, model types and HTTP client dependencies before upgrading. Check log and exec consumers against the streaming documentation.

Change the client requirement to docker-php/docker-php:^3.0. Remove an explicit docker-php/docker-php-api:4.1.* requirement, or change it to the API 1.45 range shown above. Update dependencies, test your application and commit its updated composer.lock.

Version 3.0 continues the client maintained under beluga-php/docker-php. The PHP namespaces remain Docker and Docker\API.

Remove the beluga-php/docker-php requirement and any explicit beluga-php/docker-php-api requirement from composer.json. Add docker-php/docker-php:^3.0; add the API 1.45 range above if your application requires the generated API package directly. Resolve the package changes together, then test the application and commit its updated composer.lock.

Install one package family at a time: the Beluga and original packages contain the same PHP classes.

Install dependencies and pull the image used by the integration tests:

composer install
docker pull busybox:latest

Run the test suite and static analysis:

composer run-script test-ci
composer run-script phpstan

The integration tests create Docker resources on the configured daemon. Use a development daemon when running them. See CONTRIBUTING.md for contribution instructions.

Docker PHP was created by Geoffrey Bachelet and Joel Wurtz. Development continued under beluga-php before the return to the original repositories.

MIT.