README

Framework-agnostic PHP client for the Docker Engine API, talking directly to /var/run/docker.sock over HTTP (via Guzzle).

Plain HTTP against the Docker Engine API, over the Unix socket

Installation
Quick start
Typed results
API version handling
Timeouts
Error handling
Security note
Streaming
Demultiplexing container logs
exec
TCP / TLS hosts
Registry authentication
Testing

Installation

composer require sytxlabs/dockphp

Quick start

use Sytxlabs\Dockphp\DockerClient;

$docker = new DockerClient('/var/run/docker.sock');

// Containers
$docker->containers()->list();
$docker->containers()->inspect('container-id');
$docker->containers()->start('container-id');
$docker->containers()->stop('container-id');
$docker->containers()->restart('container-id');
$docker->containers()->remove('container-id');
$docker->containers()->logs('container-id');

// Images
$docker->images()->list();
$docker->images()->inspect('nginx:latest');
$docker->images()->pull('nginx', 'latest');
$docker->images()->remove('image-id');

// Networks
$docker->networks()->list();
$docker->networks()->create('my-network');
$docker->networks()->remove('network-id');

// Volumes
$docker->volumes()->list();
$docker->volumes()->create('my-volume');
$docker->volumes()->remove('my-volume');

Typed results

list() and inspect() on Containers, Images, Networks and Volumes return typed DTOs - not raw JSON - so you get autocompletion and don't have to remember Docker's field names:

$container = $docker->containers()->inspect('container-id');
echo $container->getName();      // "web", not "/web"
echo $container->isRunning();    // bool, reads State.Running for you

$image = $docker->images()->inspect('nginx:latest');
echo $image->getName();          // "nginx:latest" (first RepoTag), or null if untagged

foreach ($docker->containers()->list(['all' => true]) as $summary) {
    echo $summary->getName(), ' - ', $summary->status, "\n";
}

Method	Returns
`containers()->list()`	`list<DTO\ContainerSummary>`
`containers()->inspect()`	`DTO\ContainerInfo`
`images()->list()`	`list<DTO\ImageSummary>`
`images()->inspect()`	`DTO\ImageInfo`
`networks()->list()` / `inspect()`	`list<DTO\NetworkInfo>` / `DTO\NetworkInfo`
`volumes()->list()` / `inspect()`	`list<DTO\VolumeInfo>` / `DTO\VolumeInfo`

Every DTO only models the commonly-needed fields (id, name, state, labels, ...) - call ->raw() on any of them to get the full, untouched decoded array for anything not promoted to a typed property.

Every other resource method (start(), stop(), remove(), create(), ...) still returns a Sytxlabs\Dockphp\Http\DockerResponse - there's no useful entity to hydrate from an action's ack/204 response. Use ->json() for the decoded body or ->getBody() for the raw string.

Creating a container

containers()->create() accepts the full Docker container config as a single array. Query-only parameters (name, platform) are automatically split out of the array and sent as query string parameters, the rest is sent as the JSON request body - you never have to think about the split:

$container = $docker->containers()->create([
    'Image' => 'nginx:latest',
    'name' => 'web',
    'HostConfig' => [
        'PortBindings' => [
            '80/tcp' => [
                ['HostPort' => '8080'],
            ],
        ],
    ],
]);

$id = $container->json()['Id'];
$docker->containers()->start($id);

Networks and volumes

networks()->create() and volumes()->create() take the name directly, with an optional array of additional Docker options:

$docker->networks()->create('my-network', ['Driver' => 'bridge']);
$docker->volumes()->create('my-volume', ['Driver' => 'local']);

API version handling

By default, the API version is not fetched eagerly when you construct DockerClient - it is resolved lazily via a single GET /version call the first time a request is made, then cached for the lifetime of the client.

You can override it manually to skip that lookup entirely and pin a specific version:

$docker = new DockerClient('/var/run/docker.sock', apiVersion: '1.43');

Timeouts

$docker = new DockerClient(
    socketPath: '/var/run/docker.sock',
    connectTimeout: 5.0, // seconds
    timeout: 30.0,       // seconds
);

Error handling

Sytxlabs\Dockphp\Exceptions\DockerConnectionException - the socket could not be reached at all (missing socket, connection refused, timeout).
Sytxlabs\Dockphp\Exceptions\DockerApiException - the Engine responded with a non-2xx HTTP status. Carries getStatusCode() and getDockerMessage() (Docker's own JSON error message, when present).
Sytxlabs\Dockphp\Exceptions\DockerNotFoundException - a DockerApiException subclass specifically for HTTP 404 (e.g. inspecting a container that doesn't exist).

use Sytxlabs\Dockphp\Exceptions\DockerNotFoundException;
use Sytxlabs\Dockphp\Exceptions\DockerApiException;
use Sytxlabs\Dockphp\Exceptions\DockerConnectionException;

try {
    $docker->containers()->inspect('does-not-exist');
} catch (DockerNotFoundException $e) {
    // 404
} catch (DockerApiException $e) {
    // any other non-2xx response
    $e->getStatusCode();
    $e->getDockerMessage();
} catch (DockerConnectionException $e) {
    // could not reach the socket at all
}

Security note

The Docker Engine API, reached through /var/run/docker.sock, grants practically full control over the Docker host. This package never changes socket permissions itself (no chmod, no ownership changes) - managing who can read/write that socket is entirely up to you and your deployment. Only grant access to the socket to trusted, trusted-equivalent code.

Streaming (logs, stats, pull/build progress, events)

Anything that can run indefinitely or produce output incrementally has a *Stream()/*Stream counterpart that invokes a callback per chunk instead of buffering the whole response. Return false from the callback to stop early:

// Follow logs
$docker->containers()->logsStream('web', function (string $chunk) {
    echo $chunk;
});

// Live stats
$docker->containers()->statsStream('web', function (string $chunk) {
    // one or more JSON objects per chunk - see NdjsonLineBuffer below
});

// Pull with progress
$docker->images()->pullStream('nginx', 'latest', null, function (array $event) {
    echo $event['status'] ?? '', "\n";
});

// Build with progress
$docker->images()->buildStream($tarContent, function (array $event) {
    echo $event['stream'] ?? '';
});

// Real-time event feed
$docker->system()->events(function (array $event) {
    echo $event['Type'], ' ', $event['Action'], "\n";
});

pullStream()/buildStream()/events() already decode newline-delimited JSON for you via Sytxlabs\Dockphp\Support\NdjsonLineBuffer. logsStream() and attachStream() hand you raw bytes instead - see the demux section below.

Demultiplexing container logs

Unless a container was created with a TTY, Docker interleaves stdout and stderr into one stream using an 8-byte frame header per chunk of output. Sytxlabs\Dockphp\Support\StdioDemultiplexer decodes that format:

use Sytxlabs\Dockphp\Support\StdioDemultiplexer;

$response = $docker->containers()->logs('web');
foreach (StdioDemultiplexer::demuxAll($response->getBody()) as $frame) {
    echo "[{$frame['stream']}] {$frame['payload']}";
}

For logsStream()/attachStream(), use a stateful instance instead so frames split across chunks are handled correctly:

$demux = new StdioDemultiplexer();
$docker->containers()->logsStream('web', function (string $chunk) use ($demux) {
    $demux->push($chunk, function (string $stream, string $payload) {
        echo "[$stream] $payload";
    });
});

exec

$exec = $docker->exec()->create('web', [
    'Cmd' => ['ls', '-la'],
    'AttachStdout' => true,
    'AttachStderr' => true,
])->json()['Id'];

$output = $docker->exec()->start($exec)->getBody();

Not supported: a fully interactive exec/attach session (writing to stdin while concurrently reading output). That needs a raw duplex socket outside of normal HTTP request/response semantics, which a per-call cURL client cannot provide. exec()->startStream() and containers()->attachStream() cover the read side; send a fixed block of input up front via the request body if you need to feed stdin.

TCP / TLS hosts

The Unix socket is the default and recommended way to connect. To reach a Docker Engine exposed over TCP instead (a remote host, or Docker Desktop's TCP endpoint):

$docker = DockerClient::tcp('docker.example.com', 2376, tls: true, caFile: '/path/ca.pem', certFile: '/path/cert.pem', keyFile: '/path/key.pem');

Registry authentication (pull/push)

pull(), pullStream(), push() and pushStream() take an optional $registryAuth array - the usual Docker auth config (username/password/serveraddress, or identitytoken). It's sent as the base64-encoded X-Registry-Auth header Docker expects:

$docker->images()->pull('registry.example.com/private/app', 'latest', registryAuth: [
    'username' => 'me',
    'password' => 'secret',
    'serveraddress' => 'registry.example.com',
]);

$docker->images()->push('registry.example.com/private/app', 'latest', registryAuth: [
    'username' => 'me',
    'password' => 'secret',
    'serveraddress' => 'registry.example.com',
]);

Testing

composer install
composer test              # unit tests, no Docker required
composer test:integration  # integration tests, requires a real Docker socket
composer stan               # static analysis (PHPStan)

Integration tests automatically skip themselves when /var/run/docker.sock is not present (e.g. on Windows, or a machine without Docker installed) - no configuration required.

License

MIT - see LICENSE.

sytxlabs / dockphp

Maintainers

Package info

Statistics

Security