Download the PHP package sytxlabs/dockphp without Composer

DockPHP

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

Contents

• 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

Quick start

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:

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:

Networks and volumes

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

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:

Timeouts

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).

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:

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:

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

exec

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):

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:

Testing

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.